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PREFACE 


This publication supports the MV5/370 Data Facility Product and 
provides application programmers with the information necessary 
to use the Linkage Editor and Loader to prepare the output of a 
language translator for execution. Additional information on the 
operation and use of the linkage editor and loader is directed 
to the system programmer responsible for installing and 
maintaining the operating system. 


The "Introduction™ defines the functions and gives 
recommendations for the use of the linkage editor and loader. 
Part 1 describes the linkage editor, and should be read before 
Part 2, which describes the loader. 


The linkage editor combines and edits modules to produce a 
single module that can be brought into storage by program fetch 
for execution. It operates as a processing program rather than 
as part of the control program. The linkage editor provides 
several processing facilities that are performed automatically 
or invoked in response to control statements prepared by the 
programmer. 


Part 1, which consists of seven chapters and four appendixes, 
describes the processing facilities and operation of the linkage 
editor. The seven chapters describe: 

° The function of the linkage editor 

° The input to the linkage editor 


° The output from the linkage editor 


e Module editing functions 

e Design and specification of overlay programs 

e The job control language necessary to run a linkage editor 
job step 

° The linkage editor control statements 


The last two chapters are summaries of reference information to 
be used after the general information in the first five chapters 
is mastered. The appendixes to Part 1 contain sample programs, 
information on the invocation of the linkage editor, storage 
requirements, and size parameter guidelines. 


The loader program combines the basic editing and loading 
functions of the linkage editor and program fetch in one job 
step. It 15s designed for high-performance loading of modules 
that do not require the special processing facilities of the 
linkage editor and fetch, such as overlay. The loader does not 
produce load modules for program libraries. 


Part 2 of this publication describes the loader. The 
introduction to this part describes the functional 
characteristics of the loader, along with its compatibility with 
the linkage editor and restrictions on its use. The chapter on 
using the loader describes: 


e The job control language statements and invocation 
procedures for the loader 


e Loader input and output 
e User program data 
The appendixes to Part 2 contain sample input, a description of 


loader return codes, storage considerations», and a description 
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PUBLICATIONS 


TIME SHARING OPTION 


of the format of the load module. All of these items are 

discussed in relation to the capabilities of the linkage editor; 
therefore, you should be familiar with Part 1 of this ) 
publication. 


The diagnostic messages issued by both the linkage editor and 
the loader program are described in Linkage Editor and Loader 
Messages. The description of each message includes an 


explanation, a system action, and a problem determination action 
to be taken. 


(TSO) 

The following publication contains procedures for invoking the 

linkage editor or loader from the terminal and gives a brief 

description of the options that can be specified under TSQ. 
OS/VS2 TSO Terminal User's Guide, GC28-0645 

Further information on TSO can be found in: 


® OS/VS2 MVS System Programming Library: TS0, GC28-06293 


° OS/VS2 TSO Command Language Reference, GC28-0646 


ADDITIONAL PUBLICATIONS 


iv MVS/370 Linkage 


For more information on the linkage editor and loader, see the 
following manuals: 


° MVS/7370 Linkage Editor and Loader Messages, GC26-4067 ) 
° MVS/370 Linkage Editor Logic, LY26-3921 
° MVS/370 Loader Logic, LY26-3922 


Within the text, references are made to the following 
publications: 


° MVS7370 Utilities, GC26-4%065 
° OS/VS2 Data Areas, SYB&8-0606 
° OS/VS2 MVS JCL, GC28-0692 


° OS/VS2 MVS System Programming Library: Initialization and 
Tuning Guide, GC28-1029 


° OS/VS2 MVS System Programming Library: Service Aids, 
GC28-067% 


e OS/VS2 MVS Supervisor Services and Macro Instructions, 
GC28-0683 


® OS/VS System Modification Program (SMP) System Programmers 
Guide, GC28-0673 


Editor and Loader 


In addition, you may wish to consult the following manuals for 
more information on specific topics. 


e MVS/370 Data Management Services, GC26-4058 


e MVS/7370 System Generation Reference, GC26-4063 


e OS/7VS Message Library: VS2 Routing and Descriptor Codes, 


GC38-1102 


OS/VS Message Library: VS2 System Codes, GC38-1008 


OS/VS Message Library: VS2 System Messages, GC38-1002 
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INTRODUCTION 


The linkage editor and the loader processing programs prepare 
the output of language translators for execution. The linkage 
editor prepares a load module that is to be brought into storage 
for execution by program fetch. The loader prepares the 
executable program in storage and passes control to it directly. 


The linkage editor provides several processing facilities, such 
as creating overlay programs and aiding program modification. 
(The linkage editor is also used to build and edit system 
libraries.) The loader provides high performance loading of 
programs that do not require the special processing facilities 
of the linkage editor. 


Use of the linkage editor is recommended in the following cases: 


° If the program requires linkage editor services in addition 
to the MAP, LET, NCAL, and SIZE options 


e If the program uses linkage editor control statements, such 
as INCLUDE, NAME, OVERLAY 


e If a load module is to be produced for a program library 


Use of the loader is recommended if the program only requires 
the use of the following linkage editor options: MAP, LET, NCAL, 
and SIZE. Because of its fewer options and because it can 
Process a job in one job step, the loader reduces editing and 
loading time by about one-half. 


Linkage editor processing is performed ina link-edit step. The 
linkage editor can be used for compile-link edit-go, 
compile-link edit, link-edit, and link-edit-go jobs. Loader 
processing is performed ina load step, which is equivalent to 
the link-edit-go steps. The loader can be used for compile-load 
and load jobs. 


The MVS/370 Data Facility Product linkage editor runs in 24-bit 
addressing mode. 


Details of how each language interfaces with the linkage editor 
can be found in the publication(€s) describing that language. 
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wal 


Linkage editor processing is a necessary step that follows the 
source program assembly or compilation of any problem program. 
The linkage editor is both a processing program anda service 
program used in association with the language translators. 


Every problem program is designed to fulfill a particular 
purpose. To achieve that purpose, the program can generally be 
divided into logical units that perform specific functions. A 
logical unit of coding that performs a function, or several 
related functions, is a module. Separate functions should be 
programmed into separate modules, a process called modular 
programming. Each module can be written in the symbolic 
language that best suits the function to be performed. (The 
symbolic languages are Assembler, ALGOL, BASIC, COBOL, FORTRAN, 
PASCAL, PL/I, and RPG.) 


Each module is separately assembled or compiled by one of the 
language translators. The input to a language translator is a 
source module; the output from a language translator is an 
object module. Before an object module can be executed, it must 
be processed by the linkage editor. The output of the linkage 
editor is a load module (Figure 1). 
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Preparing a Source Module for Execution 


An object module is in relocatable format with unexecutable 


machine code. A load module (see "Appendix H. Load Module 
Format™ on page 182) is also relocatable, but with executable 
machine code. A load module is ina format that can be loaded 


into virtual storage and relocated by program fetch (Figure 2 on 
page 3). 
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Preparing a Source Module for Execution, and Executing the Load Module 


Any module 15 composed of one or more control sections. A 
control section 1s a unit of coding Cinstructions and data) that 
is, in itself, an entity. All elements of a control section are 


loaded and executed in a constant relationship to one another. 
A control section is, therefore, the smallest separately 
relocatable unit of a program. 


Each module in the input to the linkage editor may contain 
symbolic references to control sections in other modules; such 
references are called external references. These references are 
made by means of address constants (Cadcons). The symbol 
referred to by an external reference must be either the name of 
a control section or the name of an entry point in a control 
section. Control section names and entry names are called 


external names. By matching an external reference with an 


external name, the linkage editor resolves references between 
modules. External references and external names are called 


external svmbols (Figure 3 on page 4). An external symbol is 


one that 1s defined in one module and can be referred to in 
another. 
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Output Load 
Module AB 


CSECT Al 
ENTRY All 


CALL Bl 
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ancel - so CSECT BI 
aes Bl CSECT BI 
Symbols 
External References. . 
CALL AII 
From Al to Bl ; 
trom BI to ATI CALL AI\| 
Figure 3. External Names and External References 
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Object modules and load modules have the same basic logical 
structure. Each consists of: 


e Control dictionaries, containing the information necessary 
to resolve symbolic cross-references between control 
sections of different modules, and to relocate address 
constants. Control dictionary entries are generated when 
external symbols, address constants, or control sections are 
processed by a language translator. Each language 
translator usually produces two kinds of control 
dictionaries: an external symbol dictionary CESD) anda 
relocation dictionary CRLD). 


° Text, containing the instructions and data of the program. 


® An end-of-module indication: an END statement in an object 
module, an end-of-module indicator in a load module. 


Each control dictionary, text, and end indication is described 
in greater detail below. 


Both object modules and load modules can contain data used by 
the linkage editor to create CSECT identification CIDR) records. 
If the language translator creating an object module supports 
CSECT identification, the input object module can contain 
translator data for identification records on the END statement. 
Input load modules differ from object modules in the type of 
data they supply. Input load modules can also provide HMASPZAP 
data, linkage editor data, and user data to the identification 
records that are built during linkage editor processing. During 
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the link-edit step, the optional IDENTIFY control statement is 
used to supply the optional user data for the CSECT 
identification records. See "IDENTIFY Statement” on page 119 
for more information. 


External Symbol Dictionary 


The external symbol dictionary (ESD) contains one entry for each 
external symbol defined or referred to within a module. The 
dictionary contains an entry for each external reference, pseudo 
register (external dummy section), entry name, named or unnamed 
control section, and blank or named common area. An entry name, 
pseudo register, or named control section can be referred to by 
any control section or separately processed module; an unnamed 
control section cannot. 


Each entry identifies a symbol, or a symbol reference, and gives 
its location, if known, within the module. Each entry in the 
external symbol dictionary is classified as one of the 
following: 


° External reference—a symbol that is defined as an external 
name in another separately processed module, but 1s referred 
to in the module being processed. The external symbol 
dictionary entry specifies the symbol; the location 15 
unknown. 


e bleak external reference—a special type of external 
reference that is not to be resolved by automatic library 
call unless an ordinary external reference to the same 
symbol is found. The external symbol dictionary entry 
specifies the symbol; the location is unknown. 


° Entry name—a name that defines an entry point within a 
control section. The external symbol dictionary entry 
specifies the symbol and its location, and identifies the 
control section to which it belongs. 


e Control section name—the symbolic name of a control 
section. The external symbol dictionary entry specifies the 
symbol, the length of the control section, and its location. 
In this case, the location represents the origin of the 
control section, which is the first byte of the control 
section. This external symbol dictionary entry may also 
specify the addressing mode and residence mode of the 
control section and whether or not the control section is 
read-only. 


e Blank or named common area-—a control section used to 
reserve a virtual storage area that can be referred to by 
other modules. The reserved storage area can be used, for 
example, as a communications region within a program or to 
hold data supplied at execution time. The external symbol 
dictionary entry specifies the name, if there is one, and 
the length of the area. If there is no name, the name field 
contains blanks. 


e Private code—an unnamed control section. This external 
symbol dictionary entry specifies the length of the control 
section and the origin. The name field contains blanks. 


The external symbol dictionary entry may also specify the 
addressing mode and residence mode of the control section 
and whether or not the control section is read-only. 


e Pseudo register—a special facility (corresponding to the 
external dummy section feature of Assembler H Version 2) 
that can be used to write reenterable programs. A pseudo 
register is a dynamically abtained word in virtual storage 
that can be used as a pointer to dynamically acquired 
storage; that is, the space for such areas is not reserved 
in the load module but is acquired during execution. The 
external symbol dictionary contains the name, length, 
alignment, and displacement of the pseudo register. 
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When processing input modules, the linkage editor resolves 
references between modules by matching the referenced symbols to 
defined symbols. To do this, the linkage editor searches for 
the external symbol definition in the external symbol dictionary 
of each input module. As shown in Figure 4, the linkage editor 
matches the external reference to Bl by locating the definition 
for Bl in the external symbol dictionary of Module B. In the 
same way, 1t matches the external reference to All by locating 
the definition for All in the external symbol dictionary of 
Module A. 
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Figure 4. Use of the External Symbol Dictionary 


Text 


The text contains the instructions and data of the module. 


Note: Object module text records may not necessarily be in 
ascending address sequence (it is possible that the language 
translator may have created them out of order). When processing 
large object modules with out-of-order text, the performance of 
the linkage editor may be improved by presorting the object 
module text in ascending address sequence (columns 6 through 8 
of the text record). 


Relocation Dictionary 


The relocation dictionary CRLD) contains one entry for each 
relocatable address constant that must be modified before a 
module 15s executed. An entry identifies an address constant by 
indicating both its location within a control section and the 
external symbol whose value must be used to compute the value of 
the address constant. (The external symbol is defined in an 
external symbol dictionary entry in another control section or 
module. ) 


The linkage editor uses the relocation dictionary whenever it 
processes a module to adjust the address constants for 
references to other control sections and modules. This 
dictionary is also used to adjust these address constants again 
after program fetch reads an output load module from a library 
and loads it into virtual storage for execution. 
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End Indication 


The end of a load module is marked by an end-of-module indicator 
CEOM). The EOQM cannot, unlike the assembler END instruction, 
specify an entry point. Therefore, whenever a load module 15s 
reprocessed by the linkage editor, a main entry point should be 
specified on an ENTRY statement. If one is not specified, the 
linkage editor will assign the first byte of the first control 
section encountered as the entry point. 


LINKAGE EDITOR PROCESSING 


This section discusses the input and output sources of the 
linkage editor, and the way in which the linkage editor produces 
a load module. 


INPUT AND OUTPUT SOURCES 


LOAD MODULE CREATION 


The linkage editor accepts two major types of input: 


° Primary input, which can contain only object modules and 
linkage editor control statements (called control statements 
in the following text). 


® Additional user-specified input, which can contain either 
object modules and control statements, or load modules. 
This input is either specified by the user as input, or 
incorporated automatically by the linkage editor from a call 
library. 


During processing, the linkage editor generates intermediate 
data. Intermediate data is placed on a direct access storage 
device when virtual storage allocated for input data is 
exhausted. 


Output of the linkage editor is of two types: 


e A load module, which is always placed ina library (a 
partitioned data set) as a named member 

° Diagnostic output, which is produced as a sequential data 
set 


Figure 5 on page 8 shows the input, intermediate, and output 
sources for the linkage editor program. 


In processing object and load modules, the linkage editor 
assigns consecutive relative virtual storage addresses to all 
control sections and resolves all references between control 
sections. Object modules produced by several different language 
translators can be used to form one load module. 


An output load module is composed of all input object modules 
and input load modules processed by the linkage editor. The 
control dictionaries of an output module are, therefore, a 
composite of all the control dictionaries in the linkage editor 
input. The control dictionaries of a load module are called the 
composite external symbol dictionary (CESD) and the relocation 
dictionary (RLD). The load module also contains all of the text 
from each input module, and one end-of-module indicator (see 
Figure 6 on page 9). See also "Appendix H. Load Module Format" 
on page 182 for the format of a load module. 
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Figure 5. Input, Intermediate, and Output Sources for the 
Linkage Editor 


Assigning Addresses 


Each module to be processed by the linkage editor has an origin 
that was assigned during assembly, compilation, or a previous 
execution of the linkage editor. When several modules, each 
with an independently assigned origin, are to be processed by 
the linkage editor, the sequence of the addresses 15 
unpredictable; two input modules may even have the same origin. 


Each input module can be made up of one or more control 
sections. To produce an executable output load module, the 
linkage editor assigns relative virtual storage addresses to 
each control section by assigning an origin to the first control 
section encountered and then assigning addresses, relative to 
that origin, to all other control sections to be included in the 
output load module. The value assigned as the origin of the 
control section 185 used to relocate each address-dependent item 
in the control section. 


Although the addresses in a load module are consecutive, they 
are all relative to base zero. When a load module is to be 
executed, program fetch prepares the module for execution by 
loading it at a specific virtual storage location. The 
addresses in the module are then increased by this base address. 
Each address constant must also be readjusted, another function 
of program fetch. 
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Figure 6. A Load Module Produced by the Linkage Editor 





Resolving External References 


The linkage editor also resolves external references in input 
modules. Cross-references between control sections in different 
modules are symbolic. They must be resolved relative to the 
addresses assigned to the load module. The linkage editor 
calculates the new address of each relocatable expression ina 
control section and determines the assigned origin of the item 
to which it refers. 


FUNCTIONS OF THE LINKAGE EDITOR 


Linkage editor input may consist of a combination of object 
modules, load modules, and control statements. The primary 
function of the linkage editor is to combine these modules, in 
accordance with the requirements stated on control statements, 
into a single output load module. Although this linking or 
combining of modules is its primary function, the linkage editor 
also: 


e Edits modules by replacing, deleting, rearranging, and 
ordering control sections as directed by control statements 


e Aligns control sections and named common areas on 4K-byte 
Page boundaries as directed by control statements 


e Accepts additional input modules from data sets other than 
the primary input data set, either automatically or upon 
request 

e Reserves storage for the common control sections generated 


by Assembler and FORTRAN language translators, and static 
external areas generated by PL/I 
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Links Modules 


e Computes total length and assigns displacements for all 
pseudo registers (external dummy sections) 


e Creates overlay programs ina structure defined by control 
statements 


e Creates multiple output load modules as directed by control 
statements 


e Provides special processing and diagnostic output options 


e Assigns module attributes that describe the structure, 
content, and logical format of the output load module 


e Allocates storage areas for linkage editor processing as 
specified by the programmer 


e Stores system status index information in the directory of 
the output module library (systems personnel only) 


e Traces the processing history of a program 


e Allovis the user to lengthen a control section or named 
common section without changing source code, reassembling, 
or recompliling 


e Allows the user to assign an authorization code to a load 
module that (a) makes it a restricted resource and (b) 
enables it to pass control to other restricted resources 


e Assigns an addressing mode for the main entry point, all 
true aliases, and each alternate entry point into the output 
load module 


e Assigns a residence mode for the output load module 


e Indicates which control sections are read-only Crelevant 
only in creating a nucleus load module for MVS/XA) 


Each of the linkage editor functions is described in the 
following paragraphs. 


Processing by the linkage editor makes it possible for the 
programmer to divide a program into several modules, which can 
be separately assembled or compiled, and each containing one or 
more control sections. The linkage editor combines these 
modules into one output load module (see Figure 7 on page 11) 
with contiguous, virtual storage addresses. During processing 
by the linkage editor, references between modules within the 
input are resolved. The output module is placed ina library 
(partitioned data set). 
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Figure 7. Linkage Editor Processing—Module Linkage 


Edits Modules 


Program modification is made easier by the editing functions of 
the linkage editor. When the functions of a program are 
changed, the programmer modifies, then compiles and link-edits 
again, only the affected control sections instead of the entire 
source module. 


Control sections can be replaced, renamed, deleted, moved, or 
ordered as directed by control statements. Control sections can 
also be automatically replaced by the linkage editor. External 
symbols can be changed or deleted as directed by control 
statements. 


Figure 8 on page 12 illustrates the module editing function of 
the linkage editor. 


Part 1. Linkage Editor ll 


















Object 
Module 


A 
fr cc clr 
Control 
Statements 






fT 
Linkage \\ 


Editor y), 






Load 


Module 
B 
C 





Figure 8. Linkage Editor Processing—Module Editing 


Aligns Control Sections or Common Areas on Page Boundaries 


Control sections or named common areas in the output load module 
can be aligned on 4K-byte page boundaries. Alignment on page 
boundaries enables the programmer to use real storage more 
ay and thus appreciably reduce the paging rate for the 
job. 


Accepts Additional Input Sources 


Standard subroutines can be included in the output module, thus 
reducing the work in coding programs. The programmer can 
specify that a subroutine be included at a particular time 
during the processing of the program by using a control 
statement. When the linkage editor processes a program that 
contains this statement, the module containing the subroutine is 
retrieved from the indicated input source and made a part of the 
output module (Figure 9 on page 13). 


Symbols that are still undefined after all input modules have 
been processed cause the automatic library-call mechanism to 
search for modules that will resolve these references. When a 
module name is found that matches the unresolved symbol, the 
module is processed by the linkage editor and also becomes part 
of the output module (Figure 9). 


Note: The linkage editor distinguishes a special type of 
external reference—the weak external reference. An unresolved 
weak external reference does not cause the linkage editor to use 
the automatic library-call mechanism. Instead, the reference is 
left unresolved, and the load module is marked as executable. 
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Figure 9. Linkage Editor Processing—Additional Input Sources 


The linkage editor processes common control sections generated 
by the FORTRAN and Assember language translators. The static 
external storage areas generated by the PL/I compiler are 
processed in the same way. The common areas are collected by 
the linkage editor, and a reserved virtual storage area is 
provided within the output module. 


Processes Pseudo Registers 


Pseudo registers, like the external dummy sections of Assembler 
H Version 2, aid in generating reenterable code. The linkage 
editor processes pseudo registers by accumulating the total 
length of storage required for all pseudo registers and 
recording the displacement of each. During execution, the 
program dynamically acquires the necessary storage. 


Creates Overlay Programs 


To minimize virtual storage requirements, the programmer can 
organize a program into an overlay structure by dividing it into 
segments according to the functional relationships of the 
control sections. Two or more segments that need not be in 
virtual storage at the same time can be assigned the same 
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relative virtual storage addresses, and can be loaded at 
different times. 


The programmer uses control statements to specify the 
relationship of segments within the overlay structure. The 
segments of the load module are placed ina library so that the 
control program can load them separately when the load module is 
executed. 


Creates Multiple Load Modules 


The linkage editor can also process its input to form more than 
one load module within a single job step. Each load module is 
placed in the library under a unique member name, as specified 
by a control statement. 


Provides Special Processing and Diagnestic Cutput Options 


Assigns Load Module 


The programmer can specify special processing options that 
negate automatic library call or the effect of minor errors. In 
addition, the linkage editor can produce a module map or 
cross-reference table that shows the arrangement of control 
sections in the output module and indicates how they communicate 
with one another. A list of the control statements processed 
can also be produced. 


Throughout processing, errors and possible error conditions are 
logged. Serious errors cause the linkage editor to mark the 
output module not executable. Additional diagnostic data is 
automatically logged by the linkage editor. The data indicates 
the disposition of the load module in the output module library. 


Attributes 


When the linkage editor generates a load module, it places an 
entry for the module in the directory of the library. This 
entry contains attributes that describe the structure, content, 
and logical format of the load module. The control program uses 
these attributes to determine how a module is to be loaded, what 
1t contains, if it 1s executable, whether it is executable more 
than once without reloading, and if it can be executed by 
concurrent tasks. Some module attributes can be specified by 
the programmer; others are specified by the linkage editor as a 
result of information gathered during processing. See also 
"Assigns Addressing Mode™ on page 15, "Assigns Residence Mode" 
on page 16, and "Assigns Read-only Attribute™ on page 18. 


Allocates User-Specified Virtual Storage Areas 


The programmer can specify the total amount of virtual storage 
to be made available to the linkage editor, the amount to be 
used for the load module buffer, and the buffer for the output 
load module. 


Stores System Status Index Information 


The following information is intended for systems personnel 
responsible for maintaining IBM-supplied load modules. It is 
not generally applicable to non-IBM load modules. 


Four bytes in the library directory entry for IBM-supplied load 
modules are used to store system status index information. This 
information, which is used for maintenance of the modules, 15 
placed in the directory with a control statement. 
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Traces Processing History 


Tracing the processing history of a program is simplified by the 
CSECT identification CIDR) records created and maintained by the 
linkage editor. A CSECT identification record can contain data 
that describes: 


e The language translator, its level, and the translation date 
for each control section 


e The most recent processing by the linkage editor 
e Any modification made to the executable code of any control 
section 


Optionally, user-supplied data associated with the executable 
code of a control section can also be recorded. 


Lengthens Control Sections or Named Common Sections 


The user can lengthen control sections or named common sections 
of a program to add patch space without changing the source 
code, reassembling, or recompiling. 


Added space, consisting of binary zeros, is put at the end of a 
specified control section by using the EXPAND control statement 
(see "Linkage Editor Control Statement Summary™ on page 112). 

Space cannot be added to a private code or blank common section. 


Assigns an Authorization Code to Output Load Modules 


The authorized program facility CAPF) limits the use of 
sensitive system and (Coptionally) user services and resources to 
authorized system and user programs. Authorization is defined 
as access to those services and resources. The services and 
resources to which access is limited are described in System 


Programming Library: Initialization and Tuning Guide. 


Programs are authorized at the job-step level. For a job step 
to gain authorization initially, the first module loaded at the 
start of the job step must be an authorized module, and it must 
have been loaded from an authorized library. Otherwise, the job 
step is not authorized initially and cannot subsequently gain 
authorization. 


For a job step to maintain its authorization, all subsequent 
modules invoked during the job step (via LINK, LOAD, ATTACH, 
and/or XCTL macro instructions) must be loaded from an 
authorized library. Otherwise, the job step loses its 
authorization and cannot regain authorization. 


A library becomes an “authorized” library by the inclusion of 
its name ina list called IEAAPF00. This list is described in 
more detail in System Programming Library: Initialization and 
Tuning Guide. 


A load module becomes “authorized” by the assignment of an 
authorization code to the load module during linkage-editing. 
This assignment is made via the PARM field parameter AC or via 
the control statement SETCODE, which are described in the 
sections that follow. See "SETCODE Statement” on page 136. 


Assigns Addressing Mode 


The addressing mode (AMODE) is the attribute of an entry point 
into a load module that specifies the addressing mode in effect 

rated the load module is entered at that entry point at execution 
ime. 


The valid addressing modes are: 
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24 Indicating that 24-bit addressing will be in effect 
31 Indicating that 31-bit addressing will be in effect J 


ANY Indicating that either 24-bit or 31-bit addressing may 
be in effect 


The linkage editor determines the addressing mode for an entry 
point Ceither the main entry point, its true alias, or an 
alternate entry point) according to the following rules: 


° The linkage editor assigns a default AMODE of 24. This is 
done only in the absence of a valid, explicit specification 
of the addressing mode for the entry point. 


° The linkage editor assigns the AMODE values contained in the 
object module's ESD. These AMODE values were specified by 
the user at assembly time and represent the AMODE values 
assigned to the entry points within the CSECTs and private 
code for the module. 


° The linkage editor assigns all the entry points into the 
load module (the main entry point, its true aliases, and the 
alternate entry points) the AMODE value specified as a 
parameter in the PARM field of the EXEC statement. This 
AMODE value overrides the AMODE value, if any, found in the 
ESD data. 


° The linkage editor assigns the AMODE value specified as an 
operand on the MODE control statement to all of the entry 
points into the load module (the main entry point, its true 
aliases, and the alternate entry points). This AMODE value 
overrides any value specified as a parameter in the EXEC 
statement or any values found in the ESD data. 


into the load module in its directory entry. In the case of a 
true alias of the main entry point or an alternate entry point, 
the directory entry contains the AMODE value for both the 
alias/alternate entry point and the main entry point. 


The linkage editor provides the AMODE value for each entry point ) 


The AMODE value provided to the linkage editor in the ESD data 
of an object module is retained in the ESD data of the load 
module, for use in subsequent link-editing, except in the case 
of a load module built for overlay. In building a load module 
for overlay, the AMODE value in the ESD data of the load module 
is lost and can only be reintroduced by inclusion of the object 
module(s) carrying that value. Use of the overriding AMODE 
specifications (the parameter in the PARM field of the EXEC 
statement or the operand in the MODE control statement) 
establishes the AMODE value carried in the directory entry, but 
does: not affect the ESD data. 


All entry points in load modules built for overlay are assigned 
an AMODE of 24, regardless of the ESD data, the PARM field 
parameter, or the MODE statement operand. 


Assigns Residence Mode 


The residence mode C(RMODE) is the attribute of a load module 
that specifies the residence mode of a load module when it is 
loaded into virtual storage for execution. 


The valid residence modes are: 


24 Indicating that the module must reside within 24-bit 
addressable virtual storage (that is, below the 
16-megabyte virtual storage line) 


ANY Indicating that the module may reside anywhere in ) 


virtual storage (that is, either above or below the 
16-megabyte virtual storage line) 
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The linkage editor determines the residence mode for a load 
module according to the following rules: 


e The linkage editor assigns a default RMODE of 2¢. This 
occurs only in the absence of a valid explicit specification 
of the residence mode for the load module. 


e The linkage editor assigns the RMODE specified in the object 
module. This RMODE value is specified by the user to the 
assembler for the control section or private code. The 
RMODE value passes to the linkage editor in the ESD data. 
The linkage editor assigns the RMODE value taken from the 
control section or private code that contributes to the 
output load module, ignoring identically named control 
sections and private code that are replaced or deleted. 


° As the control sections and private code that contribute to 
the output load module are processed, the RMODE value for 
the load module, based on the ESD data, is accumulated on a 
"most restrictive™ basis. This means: 


= If any section in the load module has an RMODE of 24, 
the RMODE for the load module is 24. 


= If all sections in the load module have an RMODE of ANY, 
the RMODE for the load module is ANY. 


e The linkage editor assigns to the load module the RMODE 
value specified as a parameter in the PARM field of the EXEC 
statement. This RMODE value overrides the RMODE value, if 
any, found in the ESD data. 


e The linkage editor assigns to the load module the RMODE 
value specified as an operand on the MODE control statement. 
This RMODE value overrides the RMODE value, if any, 
specified as a parameter in the PARM field of the EXEC 
statement as well as the RMODE value, if any, found in the 
ESD data. 


Load modules built for overlay are assigned an RMODE of 24, 
regardless of the ESD data, the PARM field parameter, or the 
MODE statement operand. 


The linkage editor provides the RMODE value for the load module 
in each directory entry applicable to that load module. 


Except in the case of a load module built for overlay, the RMODE 
value provided to the linkage editor in the ESD data of an 
object module is retained in the ESD data of the load module, 
for use in subsequent link-editing. In building a load module 
for overlay, the RMODE value in the ESD data of the load module 
is lost and can only be reintroduced by inclusion of the object 
module(s) carrying that value. Use of the overriding RMODE 
specifications (the parameter in the PARM field of the EXEC 
statement or the operand in the MODE control statement) 
establishes the RMODE value carried in the directory entry, but 
does not affect the ESD data. 


AMODE/RMODE Hierarchy 


The following hierarchy is used to determine the addressing and 
residence modes of the linkage editor output: 


1. Value on the linkage editor MODE statement 
2. Value of the parm field on the EXECUTE statement 


3. Value in the ESD data produced by the AMODE= or RMODE= 
assembler statement 


4. Default value of 24 
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Note: An overlay module always results in an AMODE of 24 and an 

RMODE of 24. A load module produced from multiple object 
modules results in an RMODE of 24, if any one of the object 

modules has an RMODE of 24. 


Assigns Read-only Attribute 


RELATIONSHIP TO THE 


Time Sharing Option 
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A read-only control section (RSECT) is defined by the user in 
the source language which assembles the control section. The 
assembler indicates in the external symbol dictionary entry for 
the control section that it is read-only. The linkage editor 
reflects that indication in the scatter table for the output 
load module. 


The indication of the read-only attribute is relevant only to 
the nucleus initialization program in MVS/7XA. In all other 
cases it 1s tgnored. 


OPERATING SYSTEM 


The linkage editor has the same relationship to the operating 
system as any other processing program. It can be executed 
either as a job step, a subprogram, or a subtask. Control is 
passed to the linkage editor in one of three ways: 


e As a job step, when the linkage editor is specified on an 
EXEC job control statement in the input stream 


e As a subprogram, with the execution of a CALL macro 
instruction Cafter the execution of a LOAD macro 
instruction), a LINK macro instruction, or an XCTL macro 
instruction 
e As a subtask, in multitasking systems, with the execution of 
the ATTACH macro instruction ) 
Execution of the linkage editor and the data sets used by the 
linkage editor are described to the system with job control 


language statements. These statements describe all jobs to be 
performed by the system. 


Note: Job control statements should not be confused with 
linkage editor control statements. Job control statements are 
processed before the linkage editor is executed; linkage editor 
control statements are processed during linkage editor 
execution. 


(TSO) 


When the linkage editor is used under TS0, it is invoked by the 
linkage editor prompter program that acts as an interface 
between the user, the operating system, and the linkage editor. 
Under TSO, execution of the linkage editor and definition of 
data sets used by the linkage editor are described to the system 
through use of the LINK command that causes the prompter to be 
executed. Operands of the LINK command can also be used to 
specify the linkage editor options a job requires. Complete 
procedures for use of the LINK command are given in ISO Command 
Language Reference. 


Editor and Loader 
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INPUT TO THE LINKAGE EDITOR 


The linkage editor accepts input from two major sources: the 
primary input data set and additional data sets. The primary 
input data set is made available through job control statements. 


Additional data sets are made available either through the 


automatic library call mechanism, or through user-specified 
control statements. They must, however, also be defined with 
job control statements. 


Primary and additional input data sets may contain the following 
types of data: 


e One or more object modules 

° One or more load modules 

e Control statements 

° Combinations of the above Crestrictions on certain 


combinations are noted where they apply) 


Object modules and control statements may be contained in either 
sequential or partitioned data sets. Load modules must be 
contained in partitioned data sets. 


This chapter describes the “"™linking™ functions of the linkage 
editor only; the “editing” functions are described in "Module 
Editing™ on page 45. 


FRIMARY INPUT DATA SET 


OBJECT MODULES 


The primary input data set is required for every linkage editor 
job step. It must be defined by a DD statement with the ddname 
SYSLIN. The primary input can be: 


° A sequential data set 
e A member of a partitioned data set 
e A concatenation of sequential data sets and/or members of 


partitioned data sets 


The primary input data set must contain object modules and/or 
control statements. The modules and control statements are 
processed sequentially and their order determines the basic 
order of linkage editor processing during a given execution. 
However, the order of the control sections after processing does 
not necessarily reflect the order in which they appeared in the 
Input. 


In the examples that follow, only the statements necessary to 
define the input to the linkage editor are shown; complete 
examples are shown in “Appendix A. Sample Programs" on page 138. 


The primary input to the linkage editor may consist solely of 
one or more object modules. The rest of this section discusses 
object module input from cards, as a member of a partitioned 
data set, passed from a previous job step, or created ina 
separate job. 
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From Cards 


Object module input to the linkage editor may be on cards. The 
card deck itself is treated as a sequential data set; the cards 
are placed in the input stream, after a DD * statement, as 
follows: 


//SYSLIN DD 
Object Deck A 


Object Deck B 
/*¥ 





The card input is followed by a /* statement. 


An example of the JCL when card decks are used in addition to 
other input is as follows: 


//SYSLIN DD DSNAME=INPUT,... 
// DD x 
Object Deck A 


Object Deck B 
/¥ 





By omitting the ddname on the second DD statement, the card 
input 1S concatenated to the data set described on the SYSLIN DD 
statement. 


As a Member of a Partitioned Data Set 


An object module ina partitioned data set can be used as 
primary input to the linkage editor by specifying its data set 
name and member name on the SYSLIN DD statement. In the 
following example, the member named TAXCOMP in the object module 
library LIBROUT is to be the primary input; LIBROUT is a 
cataloged data set: 


“/SYSLIN DD DSNAME=LIBROUTCTAXCOMP), 


// DISP=COLD,KEEP) 





The library member 18 processed as if it were a sequential data 
set. 


Members of partitioned data sets can be concatenated with other 
input data sets, as follows: 


“//SYSLIN DD DSNAME=OBJLIB,DISP=COLD,KEEP),... 


// DD DSNAME=LIBROUTCTAXCOMP), 
// DISP=(OLD,KEEP) 





Library member TAXCOMP is concatenated to data set OBJLIB; 
because they are the primary input, both must contain object 
modules. 
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Passed from a Previous Job Step 


An object module to be used as input can be passed from a 
previous job step to a linkage editor job step in the same job, 
as 1n a compile-link-edit job. That is, the output from the 
compiler is direct input to the linkage editor. In the 
following example, an object module that was created ina 
previous job step (STEPA) is passed to the linkage editor job 
step (STEPB): 


STEPA 


//S5YSGO DD DSNAME=&&OBJECT,DISP=CNEW,PASS),... 


STEPB 
//SYSLIN DD DSNAME=&&OBJECT, DISP=(OLD, DELETE) 





The data set name &&0BJECT, used in both job steps, identifies 
the object module as the output of the language processor on the 
SYSGO DD statement, and as the primary input to the linkage 
editor on the SYSLIN DD statement. 


Note: The double ampersand (&&) in the data set name defines a 
temporary data set. These data sets exist for the duration of 
the job and are automatically deleted at the end of the job. If 
the data set is to be preserved for longer than the duration of 
a single job, the double ampersand is not used (DSNAME=OBJECT). 


The method used in the preceding example can also be used to 
retrieve object modules created in previous steps. If the same 
data set name is used for the output of each language processor, 


one SYSLIN DD statement can be used to retrieve all the object 
modules, as follows: 


STEPA: 
//SYSGO DSNAME=&&OBJMOD, DISP=CNEW,PASS),.. 


STEPB: 


//3YSPUNCH DSNAME=&& OBJMOD,DISP=(MOD,PASS) 


STEPC: 
//SYSLIN DSNAME=&&OBJMOD, DISP=COLD, DELETE) 





The two object modules from STEPA and STEPB are placed in the 
same sequential data set, &&OBJMOD. The SYSLIN DD statement in 
STEPC causes both object modules to be used as the primary input 
to the linkage editor. 


Another method can be used to accomplish this purpose: 
concatenation of data sets. This method could be used if the 
object modules were created in previous job steps with different 
member names, as follows: 
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STEPA: 


7/5YSGO0 DSNAME=&&OBJLIBCMODA),DISP=C(NEW, 
// PASS),... 


STEPB: 


//SYSPUNCH DSNAME=-&&O0BJLIB(MODB),DISP=(MOD, 
// PASS),... 


STEPC: 


“/SYSLIN DSNAME=&&OBJLIBCMODA),DISP=COLD, 
DELETE) 
DSNAME=&&O0BJLIBCMODB),DISP=COLD, 
DELETE),VOL=REF=*%.STEPB.SYSPUNCH 





The object modules created in STEPA and STEPB were placed ina 
partitioned data set with different member names. The two 
members are concatenated in STEPC as primary input. Each member 
1S considered to be a sequential data set. 


Created in a Separate Job 


CONTROL STATEMENTS 


If the only input to the Linkage editor 1s an object module from 
a previous job, the SYSLIN DD statement contains all the 
Information necessary to locate the object module, as follows: 


//SYSLIN DD DSNAME-OBJECT,DISP=COLD,DELETE), 


7 UNIT=3350,VOLUME=SER=LIB613 





An object module created in a separate job may also be on cards, 
in which case it 1s handled as described earlier. 


The primary input data set may also consist solely of control 
statements. When the primary input is control statements, input 
modules are specified on INCLUDE control statements (see 
"Included Data Sets" on page 29). The control statements may be 
either placed in the input stream or stored in a permanent data 
set. 


In the following example, the primary input consists of control 
statements in the input stream: 


//SYSLIN DD x 


Linkage Editor Control Statements 
/¥* 
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In the next example, the primary input consists of control 
statements stored in the member INCLUDES in the partitioned data 


i set CTLSTMTS: 


//SYSLIN DD DSNAME=CTLSTMTISCINCLUDES),DISP=COLD, 
// 


KEEP),... 





In either case, the control statements can be any of those 
described in “Linkage Editor Control Statement Summary" on page 
112, as long as the rules given there are followed. 


OBJECT MODULES AND CONTROL STATEMENTS 


The primary input to the linkage editor may contain both object 


modules and control statements. The object modules and control 
statements may be in either the same data set or in different 
data sets. If the modules and statements are in the same data 


set, this data set 1s described on the SYSLIN DD statement as 
any data set is described. 


If the modules and statements are in different data sets, the 
data sets are concatenated. The control statements may be 
defined either in the input stream or as a separate data set. 


Control Statements in the Input Stream 


Control statements can be placed in the input stream and 
concatenated to an object module data set, as follows: 


. od 7/SYSLIN DD DSNAME=&&OBJECT,... 
// DD * 


Linkage Editor Control Statements 
/¥ 





Another method of handling control statements in the input 
stream 1s to use the DDNAME parameter, as follows: 


“/7SYSLIN DD DSNAME=&&OBJECT,... 
// DD DDNAME=SYSIN 


//SYSIN DD x 
Linkage Editor Control Statements 
/¥* 





Note: The linkage editor cataloged procedures use DDNAME=SYSIN 
for the SYSLIN DD statement to allow the programmer to specify 
the primary input data set required. 


Control Statements ina Separate Data Set 


concatenated to a data set that contains an object module. The 
control statements for a frequently used procedure (for example, 
a complex overlay structure or a series of INCLUDE statements) 


( A separate data set that contains control statements may be 
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can be stored permanently. In the following example, the 


members of data set CTLSTMTS contain linkage editor control 
ic One of the members is concatenated to data set : 


//7SYSLIN DD DSNAME=&&OBJECT,DISP=(OLD,DELETE),... 


// DD DSNAME=CTLSTMTSCOVLY),DISP=COLD, 
// KEEP),.. 





The control statements in the member named OVLY of the 
partitioned data set CTLSTMTS are used to structure the object 
module. 


AUTOMATIC LIBRARY CALL 


The automatic library-call mechanism is used to resolve external 
references that were not resolved during primary input 
processing. Unresolved external references found in modules 
from additional data sources are also processed by this 
mechanism. 


Note: The following discussion of automatic library call does 
not apply to unresolved weak external references; they are left 
unresolved. 


The automatic library-call mechanism involves a search of the 
directory of the automatic call library for an entry that 
matches the unresolved external reference. When a match is 
found, the entire member is processed as input to the linkage 
editor. 


Automatic library call can resolve an external reference when ») 
the following conditions exist: The external reference must be 

(1) a member name or an alias of a module in the call library, 

and (2) it must be defined as an external name in the external 

symbol dictionary of the module with that name. If the 

unresolved external reference is a member name or an alias in 

the library, but 1s not an external name in that member, the 

member is processed but the external reference remains 

unresolved unless subsequently defined. 


The automatic library-call mechanism searches the call library 
defined on the SYSLIB DD statement. The call library can 
contain either (1) object modules and control statements or (2) 
load modules; it must not contain both. 


Modules from libraries other than the SYSLIB call Library can be 
searched by the automatic library-call mechanism as directed by 
the LIBRARY control statement. The library specified in the 
control statement is searched for member names that match 
specific external references that are unresolved at the end of 
input processing. If any unresolved references are found in the 
modules located by automatic library call, they are resolved by 
another search of the library. Any external references not 
specified on a LIBRARY control statement are resolved from the 
library defined on the SYSLIB DD statement. 


In addition, two means exist to negate the automatic 

library-call mechanism. The LIBRARY statement can be used to 

negate the automatic library call for selected external 

references unresolved after input processing; the NCAL option on 

the EXEC statement can be used to negate the automatic library 

call for all external references unresolved after input 

processing. Use of the LIBRARY control statement and the NCAL 

option are discussed after the SYSLIB DD statement following. ) 
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SYSLIB DD STATEMENT 


System Call Library 


If the automatic library-call mechanism is to be used, the call 
library must be a partitioned data set described by a DD 
statement with a ddname of SYSLIB. Details concerning DCB 
requirements and record formats for SYSLIB libraries are given 
in "SYSLIB DD Statement” on page 103. The call library may be 
either a system call library or a private call library; call 
libraries may be concatenated. 


For an example of some of the system programs that have their 
own automatic call library, see Figure 10. This library must be 
defined when an object module produced by that assembler or 
compiler is to be link-edited. 


ALGOL SYS1.ALGLIB 
COBOL SY51.COBLIB 


FORTRAN SYS1.FORTLIB 


Figure 10. System Automatic Call Libraries 





The call library may contain input/output, data conversion, 
and/or other special routines (€such as Sort/Merge SYS1.SORTLIB) 
that are needed to complete the module. The assembler or 
compiler creates an external reference for these special 
routines and the linkage editor resolves the references from the 
appropriate call library. 


In the following example, a FORTRAN object module created in 


STEPA is to be link-edited in STEPB, and the FORTRAN automatic 
call library is used to resolve external references: 


STEPA: 


//SYSOBJ DSNAME=&&OBJMOD, DISP=(NEW, 
// PASS J yu 


STEPB: 


//SYSLIN DD DSNAME=&&OBJMOD, DISP=COLD, DELETE) 
//SYSLIB DD DSNAME=SYS1.FORTLIB,DISP=SHR 





The disposition of SHR on the SYSLIB DD statement means that 
other tasks that may be executing concurrently with STEPB may 
also use SYS1.FORTLIB. 


Private Call Libraries 


The SYSLIB DD statement can also describe a private, 
user-written library. In this case, the automatic library-call 
mechanism searches the private library for unresolved external 


Input to the Linkage Editor 25 


references. In the following example, unresolved external 
references are to be resolved from a private library named 
PVTPROG: 


//SYSLIB DD DSNAME=PVTPROG, DISP=SHR,UNIT=3350, 


47 VOLUME=SER=PVT002 





Concatenation of Call Libraries 


System call libraries and private call libraries may be 
concatenated either to themselves, and/or to each other. When 
libraries are concatenated, they must all be either object 
module libraries or load module libraries; they may not be 
mixed. 


If object modules from different system processors are to be 
link-edited to form one load module, the call library for each 
must be defined. This is accomplished by concatenating the 
additional call libraries to the library defined on the SYSLIB 
DD statement. In the following example, a FORTRAN object module 
and a COBOL object module are to be link-edited; the two system 
call libraries are concatenated as follows: 


//SYSLIB DD DSNAME=SYS1.FORTLIB,DISP=SHR 


// DD DSNAME=SYS1.COBLIB,DISP=SHR 





System libraries are cataloged; no unit or volume information is 
needed. 


A system call library anda private call library can also be 
concatenated in this way. For example, by adding the following 
statement to the two in the preceding example, the private call 
library PVTPROG, which is not cataloged, is concatenated to the 
two system call libraries: 


DSNAME=PVTPROG, DISP=SHR,UNIT=3350, 


VOLUME=SER=PVT002 





Any external references not resolved from the two system 
libraries are resolved from the private library. 
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The LIBRARY control statement can be used to direct the 
automatic library-call mechanism to a library other than that 
specified in the SYSLIB DD statement. Only external references 
listed on the LIBRARY statement are resolved in this way. All 
other unresolved external references are resolved from the 
library in the SYSLIB DD statement. 


The LIBRARY statement can also be used to specify external 
references that are not to be resolved by the automatic 
library-call mechanism. The LIBRARY statement specifies the 
duration of the nonresolution: either during the current linkage 
editor job step, called restricted no-call; or during this or 
any subsequent linkage editor job step, called never-call. 
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Examples of each use of the LIBRARY statement follow; a 
4 description of the format is given in "LIBRARY Statement" on 
page 123. 


Additional Call Libraries 


If the additional libraries are to be used to resolve specific 
references, the LIBRARY statement contains the ddname of a DD 
statement that describes the library. The LIBRARY statement 
also contains, in parentheses, the external references to be 
resolved from the library; that is, the names of the members to 
be used from the library. If the unresolved external reference 
is not a member name in the specified library, the reference 
remains unresolved unless subsequently defined. 


For example, two modules (DATE and TIME) from a system call 
library have been rewritten. The new modules are to be tested 
with the calling modules before they replace the old modules. 
Because the automatic library call mechanism would otherwise 
search the system call library (which is needed for other 
modules), a LIBRARY statement its used, as follows: 


“/SYSLIB DSNAME=SYS1.COBLIB,DISP=SHR 
//TESTLIB DSNAME=TEST,DISP=COLD,KEEP),... 
//SYSLIN DSNAME=ACCTROUT,... 


4/ % 
LIBRARY TESTLIBCDATE, TIME) 
7% 





Two external references, DATE and TIME, are resolved from the 
library described on the TESTLIB DD statement. All other 

a unresolved external references are resolved from the library 
described on the SYSLIB DD statement. 


Restricted No-Call Function 


The programmer can use the LIBRARY statement to specify those 
external references in the output module for which there is to 
be no library search during the current linkage editor job step. 
This 1s done by specifying the external reference(s) in 
parentheses without specifying a ddname. The reference remains 
unresolved, but the linkage editor marks the module executable. 


For example, a program contains references to two large modules 
that are called from the automatic call library. One of the 
modules has been tested and corrected; the other is to be tested 
in this job step. Rather than execute the tested module again, 
the restricted no-call function is used to prevent automatic 
library call from processing the module as follows: 
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// PGM=HEWL,PARM=LET 
J/SYSLIB DSNAME=PVTPROG, DISP=SHR,UNIT=3350, 
7 VOLUME=SER=PVT002 


/7SYSLIN DSNAME=&&PAYROL,... 
14 D x 

LIBRARY (OVERTIME) 
1¥* 





As a result, the external reference to OVERTIME is not resolved 
by automatic library call. 


Never-Call Function 


The never-call function specifies those external references that 
are not to be resolved by automatic library call during this or 
any subsequent linkage editor job step. This is done by 
specifying an asterisk followed by the external reference(s) in 
parentheses. The reference remains unresolved but the linkage 
editor marks the module executable. 


For example, a certain part of a program 1s never executed, but 
it contains an external reference to a large module (CITYTAX) 
which is no longer used by this program. However, the module is 
in a call library needed to resolve other references. Rather 
than take up storage for a module that is never used, the 
never-call function is specified, as follows: 


17 PGM=HEWL ,PARM=LET 
S/SYSLIB DSNAME=PVTPROG, DISP=SHR,UNIT=3350, 
// VOLUME=SER=PVT002 


//SYSLIN DD DSNAME=TAXROUT,DISP=OLD,... 
DD % 
*(CITYTAX) 





As a result, when program TAXROUT is link-edited, the external 
reference to CITYTAX is not resolved by automatic library call. 


NCAL OPTION 


When the NCAL option is specified, no automatic library call 
occurs to resolve external references that are unresolved after 
input processing. The NCAL option is similar to the restricted 
no-call function on the LIBRARY statement, except that the NCAL 
option negates automatic library call for all unresolved 
external references and restricted no-call negates automatic 
library call for selected unresolved external references. With 
NCAL, all external references that are unresolved after input 
processing is finished, remain unresolved. The module is, 
however, marked executable. 


The NCAL option is a special processing parameter that is ) 


specified on the EXEC statement as described in "No Automatic 
Library-Call Option™ on page 91. 
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CLUDED DATA SETS 


The INCLUDE control statement requests the linkage editor to usa 
additional data sets as input. These can be sequential data 
sets containing object modules and/or control statements, or 
members of partitioned data sets containing object modules 
and/or control statements, or load modules. 


The INCLUDE statement specifies the ddname of a DD statement 
that describes the data set to be used as additional input. If 
the DD statement describes a partitioned data set, the INCLUDE 
statement also contains the name of each member to be used. See 
"INCLUDE Statement" on page 121 for a detailed description of 
the format of the INCLUDE statement. 


When an INCLUDE control statement is encountered, the linkage 
editor processes the module or modules indicated. Figure lil 
shows the processing of an INCLUDE statement. In the 
illustration, the primary input data set i5 a sequential data 
set named OBJMOD which contains an INCLUDE statement. After 
processing the included data set, the linkage editor processes 
the next primary input item. The arrows indicate the flow of 
processing. 


If an included data set also contains an INCLUDE statement, this 
specified module 1s also processed. However, any data following 
the INCLUDE statement is not processed. 


If the OBJMOD data set shown in Figure 11 is itself included, 
the data following the INCLUDE statement for OBJLIB is not 
processed. Figure 12 on page 30 shows the flow of processing 
for this example. 


Primary Input 
Data Set OBJMOD 





Library OBJLIB 
Member MODA 


Include OBJLIB (MODA) 


Figure 11. Processing of One INCLUDE Control Statement 


Input to the Linkage Editor 29 


Primary Input Sequential 










Data Set SYSLIN Data Set OBJMOD 
\ A Library OBJLIB 
pe ea Sy Member MODA 
v Include OBJIB (MODA) 


Include OBJMOD [PRR 


7 


Figure 12. Processing of More than One INCLUDE Control Statement 


J : _ 


Including Sequential Data Sets 


Sequential data sets containing object modules and/or control 
statements can be specified by an INCLUDE control statement. In 
the following example, an INCLUDE statement specifies the 
de of two sequential data sets to be used as additional 
input: 


//ACCOUNTS DD DSNAME=ACCTROUT,DISP=COLD,KEEP),... 
/7INVENTRY DD DSNAME=INVENTRY,DISP=COLD,KEEP),... 
//SYSLIN DD DSNAME=QTREND,... 


// DD x 


INCLUDE ACCOUNTS, INVENTRY 
7% 





Each ddname could also have been specified on a separate INCLUDE 
statement; with either method, a DD statement must be specified 
for each ddname. 


Another method of doing the preceding example is given in 
"Including Concatenated Data Sets” on page 31. 

Including Library Members 
One or more members of a partitioned data set can be specified 
on an INCLUDE control statement. The member name must be 


specified on the INCLUDE statement; no member name should appear 
on the DD statement itself. 
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In the following example, one member name is specified on the 
INCLUDE statement: 


//PAYROLL DD DSNAME=PAYROUTS,DISP=(COLD,KEEP),... 
//SYSLIN DD DSNAME=&&CHECKS, DISP=(OLD,DELETE),... 


// DD 
INCLUDE PAYROLLCFICA) 
7% 





If more than one member of a partitioned data set is to be 
included, the INCLUDE statement specifies all the members to be 
used from each library. The member names appear in parentheses, 
following the data set name of the library. The member names 
are not repeated on the DD statement. 


In the following example, an INCLUDE statement specifies two 
members from each of two libraries to be used as additional 
input: 


//PAYROLL DD DSNAME=PAYROUTS,DISP=COLD,KEEP),... 
//ATTEND DD DSNAME=ATTROUTS,DISP=COLD,KEEP),... 


//SYSLIN DD * 
INCLUDE PAYROLLCFICA,TAX),ATTENDCABSENCE, OVERTIME) 
7% 





Each library could have been specified on a separate INCLUDE 
statement; with either method, a DD statement must be specified 
for each ddname. 


Another method of doing this example is given in "Including 
Concatenated Data Sets.” 


Including Concatenated Data Sets 


Several data sets can be designated as input with one INCLUDE 
statement that specifies one ddname; additional data sets are 
then concatenated to the data set described on the specified DD 
statement. When data sets are concatenated, all records must 
have the same characteristics (that 1s, format, record length, 
block size, etc.). 


SEQUENTIAL DATA SETS: In the following example, two sequential 
data sets are concatenated and then specified as input with one 
INCLUDE statement: 


//CONCAT DD DSNAME=ACCTROUT,DISP=C(OLD,KEEP),... 
// DD DSNAME=INVENTRY,DISP=COLD,KEEP),... 
//SYSLIN DD DSNAME=SALES,DISP=OLD,... 

77 


DD x 
INCLUDE CONCAT 





When the INCLUDE statement is recognized, the contents of the 
sequential data sets ACCTROUT and INVENTRY are processed. 


LIBRARY MEMBERS: Members from more than one library can be 


desitgnated as input with one ddname on an INCLUDE statement. In 
this case, all the members are listed on the INCLUDE statement; 
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the partitioned data sets are concatenated using the ddname from 
the INCLUDE statement: 


//CONCAT 
// 
S/SYSLIN 
// 


INCLUDE 
1% 


DD DSNAME=PAYROUTS,DISP=COLD,KEEP),... 
DD DSNAME=ATTROUTS,DISP=COLD,KEEP),... 
DD DSNAME=REPORT,DISP=OLD,... 

DD % 

CONCATCFICA,TAX,ABSENCE, OVERTIME) 





When the INCLUDE statement is recognized, the two libraries, 
PAYROUTS and ATTROUTS, are searched for the four members; the 
members are then processed as input. 
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( OUTPUT FROM THE LINKAGE EDITOR 


OUTPUT LOAD MODULE 


The linkage editor produces two types of output: a load module 
and diagnostic information. The principal output of the linkage 
editor is the output load module. The linkage editor always 
places this load module in a partitioned data set. In addition, 
the linkage editor issues diagnostic information. Error and/or 
warning messages, module disposition data, and optional 
diagnostic output are stored in the diagnostic output data set. 


The linkage editor produces one or more load modules (see 
"Appendix H. Load Module Format"™ on page 182) from the input 
processed. When more than one load module is produced, the 


process 1s called multiple load module processing. 


Whether or not the linkage editor produces one or more load 
modules, the following apply: 


° The load module is stored ina partitioned data set called 
the output module library. 


° The load module must have an entry point; if the programmer 
has not assigned one, the linkage editor does. 


° The output load module is assigned an authorization code. 


© During processing, the linkage editor reserves and collects 
common areas, as specified in the source language program. 


e During processing, the linkage editor accumulates total 
length and individual displacements for each pseudo register 
Cexternal dummy section). 


° During processing, the linkage editor collects and records 
identification data in the CSECT identification CIDR) 
records. 

e During the processing of a load module, the linkage editor 


deletes any private code Cunnamed control section) having a 
length of zero and any identification data associated with 
it. 


e The main entry point, each true alias, and each alternate 
entry point are assigned an addressing mode CAMODE). 


° The output load module is assigned a residence mode (RMODE). 


OUTPUT MODULE LIBRARY 


The linkage editor stores every load module it produces in the 
output module library. This library is a partitioned data set 
that must be described by a DD statement with the name SYSLMOD. 
The data set name of the library is also specified on this DD 
statement. The data set can be either temporary (defined with a 
double ampersand), or permanent (defined with a single or no 
ampersand). If the data set name is either SYS1.LINKLIB or 
SYS1.SVCLIB, it would be advisable to re-IPL the system after 
linkage editor processing is complete. This ensures that the 
corresponding data extent block (DEB) is updated to reflect 
additional extents if secondary allocation of direct-access 
space was required. 


Whether the data set is permanent or temporary, each module must 
be assigned a unique name, called the member name, to 
distinguish one load module from another. The output module can 
be assigned aliases if the programmer wants the module either 
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several different points. Each member name and alias ina load 
module library must be unique. The library member name and 
aliases for each load module appear as separate entries in the 
library directory, along with the module attributes. CSome 
module attributes can be assigned on the EXEC statement for each 
linkage editor job step; see "Module Attributes” on page 86.) 


identified by more than one name or entered for execution at ) 


Member Name 


The member name of the output load module may be specified on 
the SYSLMOD DD statement, in a NAME statement, or both. If the 
member name 15 not specified, the default is TEMPNAME. If this 
default name has been previously assigned to a load module, 
using it again will cause a failure. 


ASSIGNED ON SYSLMOD DD STATEMENT: If the member name is assigned 
on the SYSLMOD DD statement, the name is written in parentheses 
following the data set name of the library. For example: 


//SYSLMOD DD DSNAME=MATHLIBCSQ@DEV), DISP=(CNEW,KEEP), 


// UNIT=3350,SPACE=(TRK,(€100,10,1)), 
// VOLUME=SER=LIBO002 





The member name SQDEV is assigned to the load module, which is 
placed in the new library named MATHLIB. 


ASSIGNED ON NAME CONTROL STATEMENT: If the member name is not 
specified on the SYSLMOD DD statement, it may be assigned in a 
NAME control statement. For example: ) 


//SYSLMOD DD DSNAME=MATHLIB,DISP=C(NEW,KEEP),... 
//SYSLIN DSNAME=&&OBJECT,DISP=C(OLD,DELETE),... 





The member name SQDEV is assigned to the load module, which is 
placed in the library named MATHLIB. 


ASSIGNED ON BOTH: If both the SYSLMOD DD statement and the NAME 
control statement specify a member name, the names should be 
identical. If the names are different, the name on the NAME 
control statement is used as the member name. 


Note: If a "link-edit and go” sequence of job steps is 
performed and the program name in the EXEC statement of the "go" 
step contains a backward reference to the SYSLMOD DD statement 
in the "link-edit™ step, the user must ensure that the member 
name specified in the SYSLMOD DD statement is valid and is not 
overridden by a NAME control statement. 
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Alias Names 


An example of an error: 


//LKED EXEC PGM=HEWL 


//SYSLMOD DD DSNAME=&&LOADST(GO),DISP=C(NEW, 
// PASS),... 
//SYSLIN DD DSNAME=&&O0BJECT,DISP=COLD,DELETE),... 
DD % 
READ 


EXEC PGM=*.LKED.SYSLMOD 


Remember, this example is incorrect! 





The EXEC statement of the GO step specifies that the module to 
be executed is described in the LKED step in the SYSLMNOD 
statement. The system tries to locate a member named GO; 
however, the output module was assigned the name READ. 


REPLACING AN IDENTICALLY NAMED LIBRARY MEMBER: The output module 
can replace an identically named member in the library in either 
of two ways. The SYSLMOD DD statement names an existing data 
set, as follows: 


//SYSLMOD DD DSNAME=MATHLIBCSQDEV),DISP=COLD, 


// KEEP),... 





Or, the NAME control statement specifies the replace function, 
as follows: 


NAME SQ@DEVCR) 


In either case, the member named SQDEV is replaced with a new 
module of the same name. 


An output module can be assigned a maximum of 16 aliases, 
specified with the ALIAS control statement. The aliases exist 
in addition to the member name of the output module. When a 
module is referred to by an alias, execution begins at the 
external name specified by the alias. If the name specified by 
the ALIAS statement 315 not an external symbol within the module, 
the main entry point is used. 


For example, an output module is to be assigned two additional 
entry points, CODE1 and CODE2. In addition, because of a 
misunderstanding, calling modules have been written and tested 
using both ROUTONE and ROUT1 to refer to the output module. 
Rather than correct the calling modules, an alternate library 
member name Calias) is also assigned. 
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ENTRY POINT 


//7SYSLMOD DD DSNAME=PVTLIB,DISP=O0LD,UNIT=3350, 
// VOLUME=SER=LIBOO1 

7/SYSLIN DD DSNAME=&& OBJECT, DISP=(OLD, DELETE) 
// 


DD % 
ALIAS CODE1,CODE2,ROUTONE 
NAME ROUT1 
1% 





The names CODE1, CODE2, and ROUTONE appear in the library 
directory along with ROUTL, the member name. Because CODE! and 
CODE2 are defined as external symbols within the output module, 
when these names are used, execution begins at these points. 
Control may be passed to the main entry point by using either 
the member name ROUT1 or the alias ROUTONE. 


Every load module must have a main entry point. The programmer 
may specify the entry point in one of two ways: 


° On a linkage editor ENTRY control statement. 


® On an Assembler language END statement, which is the last 
statement in the source program. The assembler produces an 
object module and an END statement for the module. The 
assembler-produced END statement contains an entry point 
only if the source language END statement contained one. 


From its input, the linkage editor selects the entry point for 
the load module as follows: 


1. From the first ENTRY control statement in the input. 


23 If there 1s no ENTRY control statement in the input, from 
the first assembler-produced END statement that specifies an 
entry point. 


3. If no ENTRY control statement or no assembler-produced END 
statement specifies an entry point, the first byte of the 
first control section of the load module is used as the 
entry point. 


In general, the entry point should be explicitly specified, 
because it is not always possible to predict which control 
section will be first in the output module. 


When a load module is reprocessed by the linkage editor, it has 
no END statement. Therefore, if the first byte of the first 
control section of the load module is not a suitable entry 
point, the entry point must be specified in one of two ways: 


® Through an ENTRY control statement. 


° Through the assembler-produced END statement of another 
Input module, which 1s being processed for the first time. 
This object module must be the first such module to be 
processed by the linkage editor. 


An entry point other than the main entry point may be specified 
with an ALIAS control statement. The symbol specified on the 
ALIAS statement must be defined as an external symbol in the 
load module. Any reference to that symbol causes execution of 
the module to begin at that point instead of at the main entry 
point. 


In the following example, assume that CDCHECK, CODE1, and CODE2 
are defined as external symbols in the output module: 
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/SYSLIN DD DSNAME=&& OBJECT, DISP=C(OLD, DELETE) 
// DD ¥ 
ENTRY CDCHECK 


ALIAS CODE1,CODE2,ROUTONE 
NAME ROUT1 
7% 





As a result of the preceding control statements, CDCHECK is the 
main entry point; CODE1 and CODE2 are additional entry points. 
Any reference to ROUTONE or ROUTI1 causes execution to begin at 
CDCHECK; any reference to CODE1 and CODE2 causes execution to 
begin at these points. 


Authorization Code 


Each load module link-edited is assigned an authorization code 
that determines whether or not the module is allowed to use 
restricted system services and resources. A nonzero code allows 
the module to use restricted services and resources; a zero code 
disallows that usage. The authorization code becomes part of 
the directory entry for the module in the library containing the 
module. 


Residence and Addressing Modes 


Each entry in the library directory for the output load module 
Cone for the main entry point and one for each true alias or 
alternate entry point) contains an indication of the residence 
mode for the load module and an indication of the addressing 
mode for that entry point. The entries for true aliases and 
alternate entry points also contain an indication of the 
addressing mode for the main entry point. 


RESERVING STORAGE IN THE OUTPUT LOAD MODULE 


In FORTRAN, Assembler language, and PL/I, the programmer can 
create control sections that reserve virtual storage areas that 
contain no data or instructions. These control sections are 
called "common" or "static external” areas, and are produced in 
the object modules by the language translators. These common 
areas are used, for example, as communication regions for 
different parts of a program or to reserve virtual storage areas 
for data supplied at execution time. These common areas are 
either named or unnamed (blank). 


COLLECTION OF COMMON AREAS: During processing, the linkage 
editor collects common areas. That is, if two or more blank 
common areas are found in the input, the largest blank common 
area 1S used in the output module; all references to a blank 
common area refer to the one retained. If two or more named 
common areas have the same name, the largest of the identically 
named common areas 15 used in the output module; all references 
to the named common areas refer to the one area retained. 


IDENTICALLY NAMED COMHON AREAS AND CONTROL SECTIONS: If a 
control section (as 185 generated from a BLOCK DATA subprogram in 
FORTRAN, for example) and a named common area have the same 
name, the length of the control section must be greater than or 
equal to the length of the named common area. If the control 
section 15 smaller in length than the named common area, a 
diagnostic message 1s issued. The control section is regarded 
as the largest of the common areas processed with that name. 

All subsequent control sections and/or common areas with the 
same name are ignored. 
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PROCESSING PSEUDO REGISTERS 


In PL/I, programmers can use pseudo registers to define storage ) 
that will not be reserved in the load module but can be 

allocated dynamically during execution. The external dummy 

sections generated by Assembler H Version 2 correspond to the 

pseudo registers of PL/I. 


The linkage editor accumulates the total length of all pseudo 
registers in the input and records the displacement of each. If 
two or more pseudo registers have the same name, the one with 
the longest length and the most restrictive alignment will be 
retained. All other pseudo registers with the same name will be 
ignored; all references to the identically named pseudo 
registers will refer to the one retained. 


MULTIPLE LOAD MODULE PROCESSING 


The linkage editor can produce more than one load module in a 
single job step. A NAME control statement in the input stream 
is used as a delimiter for input to a load module. If 
additional input modules follow the NAME statement in the input 
stream, they are used in the formation of the next load module. 


Each load module that is formed has a unique name and is placed 
in the same library as a separate member. When processing 
multiple load modules ina single job step, the options and 
attributes specified in the EXEC statement for that job step 
apply to all load modules created. If the linkage editor 
terminates abnormally during processing of any of the output 
modules, neither that module nor any of the modules yet to be 
processed in the job step 1s processed or placed in the library. 
Load modules processed before abnormal termination have already 
been placed in the library. 


In the following example, two load modules are produced in one ) 
linkage editor job step: 


//LKED EXEC PGM=HEWL,PARM="MAP,LIST' 


//5YSLMOD DD DSNAME=PAYROLLCOVERTIME),DISP=OLD, 
// UNIT=3350,VOLUME=SER=LIBO02 


//MODTWO DD DSNAME=&& OBJECT, DISP=COLD, DELETE) 
//SYSLIN DD DSNAME=&&OBJECTCA), DISP=COLD, DELETE) 
DD x 
INIT 
OVERTIME 
INCLUDE MODTWOCB) 
ENTRY HSKEEP 
NAME VACATION 





The first load module is produced from the object module in the 
data set defined on the SYSLIN DD statement. The main entry 
point is INIT and the member name is OVERTIME. 


The second load module is produced from the object module 
specified by the INCLUDE statement. The main entry point is 
HSKEEP and the member name is VACATION. ) 


If an INCLUDE statement specifies a member name that 1s 
different from the member name on the DD statement, the member 


38 MVS/370 Linkage Editor and Loader 


DIAGNOSTIC OUTPUT 


DIAGNOSTIC MESSAGES 


specified on the DD statement must exist even though it 1s not 
to be included. 


Both load modules are placed in the library PAYROLL, defined on 
the SYSLMOD statement. 


The parameters on the EXEC card specify that a module map anda 
control statement listing are produced for each load module. 
The map and listing are discussed in detail in the next section. 


Diagnostic information is stored in the diagnostic output data 
set, which must be defined by a DD statement with the name 
SYSPRINT. This output is a collection of messages generated by 
the linkage editor, as well as any optional output requested by 
the programmer. 


The linkage editor generates two types of messages: module 
disposition messages and error/warning messages. Descriptions 
of the error/warning messages will be found in Linkage Editor 
and Loader Messages. 


Module Disposition Messages 


Module disposition messages of several types are printed for 
each load module produced. The first message indicates the 
options and attributes specified for each module. Invalid 
options or attributes are replaced by INVALID in the output. 
Messages are also generated to inform the programmer that 
incompatible attributes have been specified. 


Disposition messages also describe the handling of the load 
module. These messages are preceded by several asterisks, and 
are: 


° member name NOW ADDED TO DATE SET. 
° member name NOW REPLACED IN DATA SET. 


e member name DOES NOT EXIST BUT HAS BEEN ADDED TO THE DATA 
SET. 


The replacement function was specified, but the member did 
not exist in the data set; the module is added to the data 
set using the member name given. 


° alias name IS AN ALIAS FOR THIS MEMBER. 
° MODULE HAS BEEN MARKED NOT EXECUTABLE. 


In addition, module disposition messages are used when the 
reenterable (RENT), reusable (REUS), and/or refreshable (REFR) 
linkage editor options have been specified for the module. When 
one or more of these module attributes have been indicated, a 
message informs the user what attribute(s) have been assigned to 
the module. This message indicates whether the load module has 
been marked reenterable or not reenterable, reusable or not 
reusable, refreshable or not refreshable, depending on the 
option or options used. (See "Reusability Attributes” on page 
87 and "Refreshable Attribute” on page 88 for more information 
on these options.) 


The message consists of several asterisks and MODULE HAS BEEN 
MARKED, followed by the attribute(s) assigned as a result of the 
linkage editor options specified. The programmer, of course, is 
responsible for verifying that the module actually is 
reenterable, reusable, and/or refreshable. The following 
messages are examples of some possible combinations: 
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e MODULE HAS BEEN MARKED REFRESHABLE. 

° MODULE HAS BEEN MARKED NOT REFRESHABLE. 

e MODULE HAS BEEN MARKED REUSABLE AND NOT REFRESHABLE. 

° MODULE HAS BEEN MARKED REUSABLE AND REFRESHABLE. 

When an error causes the linkage editor to mark a module not 


executable, only the MODULE HAS BEEN MARKED NOT EXECUTABLE 
message appears; no attribute messages are generated. 


Error/Warning Messages 


40 


Certain conditions that are present when a module is being 
processed can cause an error or warning message to be printed. 
These messages contain a message code and message text. If an 
error 1S encountered during processing, the message code for 
that error is printed with the applicable symbol or record in 
error. After processing 15 completed, the diagnostic message 
associated with that code is printed. The error warning 
messages have the following format: 


IEWNOmms message text 

where: 

IEWO indicates a linkage editor message 
mm is the message number 


Ss 1s the severity code, and may be one of the following 
values: 


l Indicates a condition that may cause an 
error during execution of the output module. 
A module map or cross-reference table is 
produced if specified by the programmer. The 
output module 1s marked executable. 


2 Indicates an error that could make execution 
of the output module impossible. Processing 
continues. When possible, a module map or a 
cross-reference table is produced if 
specified by the programmer. The output 
module is marked not executable, unless the 
LET option is specified on the EXEC 
statement. 


3 Indicates an error that will make execution 
of the output module impossible. Processing 
continues. When possible, a module map or a 
cross-reference table is produced if 
specified by the programmer. The output 
module is marked not executable. 


4G Indicates an error condition from which no 
recovery is possible. Processing terminates. 
The only output 1s diagnostic messages. 


Note: <A special severity code of zero is generated for each 
control statement printed as a result of the LIST option. 
Severity zero does not indicate an error warning condition. 


The highest severity code encountered during processing 15s 
multiplied by ¢ to create a return code that is placed in 
register 15 at the end of processing. This return code can be 
tested to determine whether or not processing is to continue 
(see "EXEC Statement—Return Code™ on page 100). 
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message text contains combinations of the following: 


e The message classification Ceither error or warning)? 
e Cause of error 
° Identification of the symbol, segment number Cwhen in 


overlay), or input item to which the message applies 
e Instructions to the programmer 
e Action taken by the linkage editor 


Optionally, error/warning messages can be sent to a separate 
output data set, which is defined by specifying TERM in the PARM 
field of the EXEC statement and including a SYSTERM DD 
statement. This separate SYSTERM data set consists of only 
numbered error/warning messages. It supplements the SYSPRINT 
output data set, which can also include module disposition 
messages and optional diagnostic output. When SYSTERM is used, 
the numbered error/warning messagesS appear in both data sets. 


Linkage Editor and Loader Messages contains a complete list of 
error/wWarning messages. 


Sample Diagnostic Output 


OPTIONAL OUTPUT 


Figure 13 on page 42 shows the format of the diagnostic output 
for the linkage editor. No optional output was requested other 
than the list of control statements. 


The letters indicate the disposition and error/warning messages 
as follows: 


A Is a module disposition message that lists the options 
and attributes specified. Additional information is 
printed indicating the variable and default options 
used. 


B Is a list of control statements used (IEWO000) and the 
message codes (CIEW0201 and IEW0461) for error/warning 
conditions discovered during processing. For 
error/warning message codes, the symbol in error, if 
necessary, 15 also listed (CCCCCCCC and BASEDUMP). 


Cc Is a module disposition message (**¥**) that indicates 
that the output module (CBBBBBBBB) has been added to 
the output module data set. 


D Is the diagnostic message directory that contains the 
text of the error codes listed in item B 


In addition to error/warning and disposition messages, the 
linkage editor can produce diagnostic output as requested by the 
programmer. This optional output includes a control statement 
listing, a module map, and a cross-reference table. 


Control Statement Listing 


If the LIST option is specified on the EXEC statement, a listing 
of all linkage editor control statements is produced. For each 
control statement, the listing contains a special message code, 
IEWO000, followed by the control statement. Item B in Figure 13 
on page 42 contains an example of a control statement listing. 
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> 


F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED LET,NCAL,XREF,OVLY,LIST 
DEFAULT OPTIONS(S) USED - SIZE=(65536,6144) 


B IEWO000 NAME BBBBBBBB 
IEWO201 
IEWO461 CCCCCCCC 
IEW0461 BASECUMP 
C ****#BBBBRBBBR NOW ADDED TO DATA SET 
DIAGNOSTIC MESSAGE DIRECTORY 
D IEW0201 WARNING - OVERLAY STRUCTURE CONTAINS ONLY ONE SEGMENT -- OVERLY OPTION 


CANCELED. 
IEWO461 WARNING - SYMBOL PRINTED IS AN UNRESOLVED EXTERNAL REFERENCE, NCAL WAS 
SPECIFIED. 


Figure 13. Diagnostic Messages Issued by the Linkage Editor 


Module Map 


If the MAP option is specified on the EXEC statement, a module 
map of the output load module is produced. The module map shows 
all control sections in the output module and all entry names in 
en control section. Named common areas are listed as control 
sections. 


For each control section, the module map indicates its origin 
(relative to zero) and length in bytes Cin hexadecimal 
notation). For each entry name in each control section, the 
module map indicates the location at which the name is defined. 
These locations are also relative to zero. 


If the module is not in an overlay structure, the control 
sections are arranged in ascending order according to their 
origins. An entry name is listed with the control section in 
which it is defined. 


If the module is an overlay structure, the control sections are 
arranged by segment. The segments are listed as they appear in 
the overlay structure, top to bottom, left to right, and region 
by region. Within each segment, the control sections and their 
corresponding entry names are listed in ascending order 
according to their assigned origins. The number of the segment 
in which they appear is also listed. 
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CONTROL SECTION 


NAME ORIGIN 


COBSUB 
$PRIVATE 


MAINMOD 
ILBODSPO®* 
ILBOSTPO* 


ENTRY ADDRESS 
TOTAL LENGTH 


$498*G0 


00 
340 


430 
598 
B80 


DOES NOT 


In any module map, the following are identified by a dollar 
sign: 


° Blank common area 
e Private code Cunnamed control section) 
e For overlay programs, the segment table and each entry table 


When the load module processed by the linkage editor does not 
have an origin of zero, the linkage editor generates a one-byte 
private code Cunnamed control section) as the first text record. 
This private code is deleted in any subsequent reprocessing of 
the load module by the linkage editor. 


Each control section that is obtained from a call library during 
automatic library call is identified by an asterisk after the 
control section name. 


At the end of the module map is the entry address, that is, the 
relative address of the main entry point. The entry address is 
followed by the total length of the module in bytes; in the case 
of an overlay module, the length is that of the longest path. 
Pseudo registers, if used, also appear at the end of the module 
map; the name, length, and displacement of each pseudo register 
are given. 


Figure 14 contains a module map with five control sections. 
There are two named control sections (COBSUB snd MAINMOD), one 
unnamed control section (designated by $PRIVATE), and two 
control sections obtained from a call library CILBODSPO and 
ILBOSTPO0). In addition, two entry names are defined: SUB1 in 
the eae control section and ILBOSTP1 in control section 
ILBOSTPO. 


ENTRY 


NAME. LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
SUB1 340 
ILBOSTP1 BI6 


EXIST BUT HAS BEEN ADDED TO DATA SET 


Figure 14. Module Map 





Cross-Reference Table 


If the XREF option is specified on the EXEC statement, a 
cross-reference table is produced. The cross-reference table 
consists of a module map anda list of cross-references for each 
control section. Each address constant that refers to a symbol 
defined in another control section is listed with its assigned 
location, the symbol referred to, and the name of the control 
section in which the symbol is defined. When control sections 
are compiled together, and simple address constants are used to 
refer from one control section to another Cinstead of using 
external symbols and entry names), the control section name is 
listed as the symbol referred to. 
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CONTROL SECTION 
NAME ORIGIN 


COBSUB 00 
$PRIVATE 340 
MAINMOD 430 


ILBODSPO* 598 
ILBOSTPO® B80 


LOCATION REFERS TO SYMBOL 


ILBOSTPO 
ILBOSTP1 
COBSUB 
430 
BBS 


250 

258 

478 
ENTRY ADDRESS 
TOTAL LENGTH 


Figure 15. 


LENGTH 
33A 
EF 


166 
SE2 


35, 


For overlay programs, this information is provided for each 
segment; in addition, the number of the segment in which the 
symbol is defined, is provided. 


If a symbol is unresolved after processing by the linkage 
editor, it is identified by SUNRESOLVED in the list. However, 
if an unresolved symbol is marked by the never-call function (as 
specified on a LIBRARY control statement), it is identified by 
SNEVER-CALL. If an unresolved symbol is a weak external 
reference, it is identified by SUNRESOLVED(W). 


Figure 15 contains a cross-reference table for the same program 
whose module map is shown in Figure 14 on page 43. All the 
information from the module map is present, plus a list of 
cross-references for each control section. 


CROSS=REFERENCE TABLE 


ENTRY 


NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
SUB) 340 
ILBOSTP1 B96 
IN CONTROL SECTION LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
ILBOSTPO 254 ILBODSPO ILBODSPO 
ILBOSTPO 450 SUB1 


COBSUB 


Cross-Reference Table 
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MODULE EDITING 


The linkage editor performs editing functions either 
automatically or as directed by control statements. These 
editing functions provide for program modification on a control 
section basis. That is, they make it possible to modify a 
control section within an object or load module, without 
recompiling the entire source program. 


The editing functions can modify either an entire control 
section or external symbols within a control section. Control 
sections can be deleted, replaced, or arranged in sequence; 
external symbols can be deleted or changed. CExternal symbols 
are control section names, entry names, external references, 
named common areas, or pseudo registers. ) 


Whatever function is used, it is requested in reference to an 
input module. The resulting output load module reflects the 
request. That is, no actual change, deletion, or replacement is 
made to an input module. The requested alterations are used to 
control linkage editor processing (Figure 16). 





Input Modules JCL and Control Statements Output Load Module 
MODAI 
es ge 
CSECTA 
//SYSLMOD DD DSNAME=NEWLIB(MODA1A2 ), <7 een 
//MODATWO DD DSNAME=MODA2, 
//SYSLIN DD DSNAME=MODA1, 
me PE DD * CSECTA 
ENTRY CSECT3 
a REPLACE CSECT2(CSECTA ) 
INCLUDE MODATWO 





CSECT3 


CSECT2 


CSECT3 





Figure 16. Editing a Module 


Editing Conventions 


In requesting editing functions, certain conventions should be 
followed to ensure that the specified modification is processed 


correctly. These conventions concern the following items: 
e Entry points for the new module 
e Placement of control statements 
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e Identical old and new symbols 
) 


ENTRY POINTS: Each time the linkage editor reprocesses a load 
module, the entry point for the output module should be 
specified in one of two ways: 


° Through an ENTRY control statement. 


e Through the assembler-produced END statement of an input 
object module, if one is present. If the entry point 
specified in the assembler-produced END statement is not 
defined in the object module, the entry name must be defined 
as an external reference. 


The entry point assigned must be defined as an external name 
within the resulting load module. 


PLACEMENT OF CONTROL STATEMENTS: The control statement Csuch as 
CHANGE or REPLACE) used to specify an editing function must 
precede either the module to be modified, or the INCLUDE 
statement that specifies the module. If an INCLUDE statement 
specifies several modules, the CHANGE or REPLACE statement 
applies only to the first module included. 


IDENTICAL OLD AND NEW SYMBOLS: The same symbol should not appear 
as both an old external symbol and a new external symbol in one 
linkage editor run. If a control section is to be replaced by 
another control section with the same name, the linkage editor 
handles this automatically (see "Automatic Replacement" on page 
49). 
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CHANGING EXTERNAL SYMBOLS 


The linkage editor can be directed to change an external symbol 
to a new symbol while processing an input module. External 
references and address constants within the module automatically 
refer to the new symbol. External references from other modules 
to a changed external symbol must be changed with separate 
control statements. 


Both the old and the new symbols are specified on either a 
CHANGE control statement or a REPLACE control statement. The 
use of the old symbol within the module determines whether the 
new symbol becomes a control sectton name, an entry name, or an 
external reference. The old symbol appears first, followed by 
the new symbol in parentheses. 


The CHANGE control statement changes a control section name, an 
entry name, or an external reference. The REPLACE statement 
changes or deletes an entry name; if the symbols on a REPLACE 
statement are control section names, the entire control section 
Lee ncee or deleted (see "Replacing Control Sections” on page 


The CHANGE statement must immediately precede either the input 
module that contains the external symbol to be changed, or the 
INCLUDE statement that specifies the input module. The scope of 
the CHANGE statement is across the immediately following module 
Cobject module or load module). The END record in the 
immediately following object module or the end-of-module 
indication in the load module terminates the action of the 
CHANGE statement. 


In the following example, assume that SUBONE is defined as an 
external reference in the input load module. A CHANGE statement 
17s used to change the external reference to NEWMOD CFigure 17 on 
page 48). 


//SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,UNIT=3350, 
// VOLUME=SER=PVT002 
//SYSLIN DD x 

ENTRY BEGIN 


CHANGE SUBONECNEWMOD) 
INCLUDE SYSLMODCMAINROUT) 
NAME MAINROUTCR) 

7% 
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Input Module 


MAINROUT 


BEGIN ENTRY 


CALL SUBONE 


CALL SUBONE 


CALL SUBONE 
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MAINROUT 


MAINEP ENTRY 


/ /SYSLMOD DD DSNAME=PVTLIB,... CALL NEWMOD 
//SYSLIN DD * 
ENTRY MAINEP | 
x CHANGE SUBONE( NEWMOD ), BEGIN( MAINEP) | CALL NEWMOD 
INCLUDE SYSLMOD( MAINROUT ) 
NAME MAINROUT( R) 
/* 


CALL NEWMOD 





Figure 17. Changing an External Reference and an Entry Point 


In the load module MAINROUT, every reference to SUBONE is 
changed to NEWMOD. Note also that the INCLUDE statement 
specifies a ddname of SYSLMOD. This allows a library to be used 
both as input and as the output module library. 


More than one change can be specified on the same control 
statement. If, in the same example, the entry point is also to 
be changed, the two changes can be specified at once (see 
Figure 17). 


7/SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,UNIT=3350, 
// VOLUME=SER=PVT002 
//SYSLIN DD x 

ENTRY MAINEP 


CHANGE SUBONECNEWMOD) ,BEGINCMAINEP) 
INCLUDE SYSLMODCMAINROUT ) 
NAME MAINROUTCR) 

/* 





The main entry point is now MAINEP instead of BEGIN. The ENTRY 
control statement specifies the new entry point, because this is 
the source of the name that is entered in the library directory 
entry for the load module's entry point. 


REPLACING CONTROL SECTIONS 


An entire control section can be replaced with a new control 
section. Control sections can be replaced either automatically 
or with a REPLACE control statement. Automatic replacement acts 
upon all input modules; the REPLACE statement acts only upon the 
module that follows it. 


Notes: 


1. Any CSECT identification CIDR) records associated with a 
particular control section are also replaced. 
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ae (For Assembler language programmers only.) When some but 
not all control sections of a separately assembled module 
are to be replaced, A-type address constants that refer to a 
deleted symbol will be incorrectly resolved unless the entry 
name is at the same displacement from the origin in both the 


old and the new control section. If all control sections of 
a separately assembled module are replaced, no restrictions 
apply. 


AUTOMATIC REPLACEMENT 


Example l 


Control sections are automatically replaced if both the old and 
the new control section have the same name. The first of the 
identically named control sections processed by the linkage 
editor is made a part of the output module. All subsequent 
identically named control sections are ignored; external 
references to identically named control sections are resolved 
with respect to the first one processed. Therefore, to cause 
automatic replacement, the new control section must have the 
same name as the control section to be replaced, and must be 
processed before the old control section. 


Caution: Automatic replacement applies to duplicate control 
section names only; if duplicate entry points exist in control 
sections with different names, a REPLACE control statement must 
be used to specify the entry point name. If a control section 
being automatically replaced contains unresolved external 
references and the control section replacing it does not, the 
parameter NCAL must be specified or the unresolved external 
references must be explicitly deleted using the REPLACE 
statement or marked for restricted no-call or never-call using 
the LIBRARY statement; otherwise, the unresolved external 
reference 1s retained. 


NOTE ON OVERLAY PROGRAMS: When identically named control 
sections appear in modules being placed in an overlay structure, 
the second and any subsequent control sections with that name 
are ignored. This occurs whether the modules are in segments in 
the same path or in exclusive segments. Resolution of external 
references may therefore cause invalid exclusive references. 
Invalid exclusive references cause the linkage editor to mark 
the output module not executable unless the exclusive call 
(XCAL) option is specified on the EXEC statement (see "Job 
Control Language Summary" on page 85). 


An object module deck contains two control sections, READ and 
WRITE; member INOUT of library PVTLIB also contains a control 
section WRITE. 


//SVYSLMOD DD DSNAME=PVTLIB,DISP=OLD,UNIT=3350, 
// VOLUME=SER=PVT002 
//3YSLIN DD as 


Object Deck for READ 


Object Deck for WRITE 


ENTRY READIN 
INCLUDE SYSLMODCINOUT ) 
NAME INOUTCR) 

7% 





The output load module contains the new READ control section, 
the new WRITE control section (replacing the old WRITE control 
section in member INOUT), and all remaining control sections 
from INOUT. 
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Example 2 


A large load module named PAYROLL, originally written in COBOL, 
contains many control sections. Two control sections, FICA and 
STATETAX, were recompiled and passed to the linkage editor job 
step in the &&O0BJECT data set. Then, by including the load 
module PAYROLL Ca member of the partitioned data set LIBQ0Q1) as 
well as the output of the language translator, the modified 
control sections automatically replace the identically named 
control sections (Figure 18 on page 51). 


//SYSLMOD DD DSNAME=LIBOQO2CPAYROLL),DISP=OLD, 
7 UNIT=3350,VOLUME=SER=LIBO02 
//SYSLIB DD DSNAME=SYS1.COBLIB,DISP=SHR 
//OQLDLOAD DD DSNAME=LIB001,DISP=COLD,DELETE), 
7 UNIT=3350,VOLUME=SER=LIBOO1] 


/7SYSLIN DD DSNAME=&&OBJECT, DISP=(OLD, DELETE) 
7 DD xX 

INCLUDE OLDLOADCPAYROLL) 

ENTRY INIT1 
1% 
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(new) 
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Output Load Module 


LIBO02 
(Payroll) 


rae //SYSLMOD DD DSNAME=LIBOO2(PAYROLL),... STATETAX 
“. / /OLDLOAD DD DSNAME=LIBOOL peoee (new ) 
MAINROUT //SYSLIN DD DSNAME=&&OBJECT,... 
ep DD * 
INCLUDE OLDLOAD (PAYROLL) 
OVERTIME ENTRY INITI 
Vis 


FICA 
(old) 


STATETAX 
(old) 
FEDTAX 


ILLACC 


VAKTION 





Figure 18. 


REPLACE STATEMENT 


FEDTAX 
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VAKTION 





Automatic Replacement of Control Sections 


The output module contains the modified FICA and STATETAX 
control sections and the rest of the control sections from the 
old PAYROLL module. The main entry point is INIT1, and the 
output module is placed ina library named LIBO002. The COBOL 
automatic call library is used to resolve any external 
references that may be unresolved after the SYSLIN data sets are 
processed. 


The REPLACE statement is used to replace control sections when 
the old and the new control sections have different names. The 
name of the old control section appears first, followed by the 
name of the new control section in parentheses. The REPLACE 
statement must precede either the input module that contains the 
control section to be replaced, or the INCLUDE statement that 
specifies the input module. The scope of the REPLACE statement 
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is across the immediately following module Cobject module or 
load module). The END record in the immediately following 
object module or the end-of-module indication in the load module 
terminates the action of the REPLACE statement. 


An external reference to the old control section from within the 
same input module is resolved to the new control section. An 
external reference to the old control section from any other 
module becomes an unresolved external reference unless one of 
the following occurs: 


° The external reference to the old control section is changed 
to the new control section with a separate CHANGE control 
statement. 

° The same entry name appears in the new control section or in 


some other control section in the linkage editor input. 


In the following example, the REPLACE statement is used to 
replace one control section with another of a different name. 
Assume that the old control section SEARCH is in library member 
TBLESRCH, and that the new control section BINSRCH is in the 
data set &£&O0BJECT, which was passed from a previous step 
(Figure 19 on page 53). 


//SYSLMOD DD DSNAME=SRCHRITN, DISP=OLD,UNIT=3350, 
/7 VOLUME=SER=SRCHLIB 

/SYSLIN DD DSNAME=&&OBJECT, DISP=(COLD, DELETE) 
/7/ 


DD x 
ENTRY READIN 
REPLACE SEARCHCBINSRCH) 
INCLUDE SYSLMODCTBLESRCH) 
NAME TBLESRCHCR) 


1% ) 
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Input Modules 


&KOBJECT 


BINSRCH 


TBLESRCH 


READIN TE NTRY 


CALL SEARCH 


SEARCH 


Figure 19. 





JCL and Control Statements Output Load Module 
//SYSLMOD DD DSNAME=SRCHRIN.... 
—» //SYSLIN DD DSNAME=&&OBJECT.... 

ee DD * TBLESRCH 
BARRY READTN 
REPLACE SEARCH (BINSEARCH) READIN ENTRY 
INCLUDE SYSLMOD (TBLESRCH) 
IW AASLE TBLES RCH (R) ; 

ge CALL BINSRCH 


BINSRCH 





Replacing a Control Section with the REPLACE Control Statement 


The output module contains BINSRCH instead of SEARCH; any 
references to SEARCH within the module refer to BINSRCH. Any 
external references to SEARCH from other modules will not be 
resolved to BINSRCH. 


DELETING A CONTROL SECTION OR ENTRY NAME 


The REPLACE statement can be used to delete a control section or 
an entry name. The REPLACE statement must immediately precede 
either the module that contains the control section or entry 
name to be deleted or the INCLUDE statement that specifies the 
module. Only one symbol appears on the REPLACE statement; the 
appropriate deletion i585 made depending on how the symbol is 
defined in the module. 


If the symbol is a control section name, the entire control 
section is deleted. The control section name is deleted from 
the external symbol dictionary only if no address constants 
refer to the name from within the same input module. If an 
address constant does refer to it, the control section name is 
changed to an external record. 


The preceding is also true of an entry name to be deleted. Any 
references to it from within the input module cause the entry 
name to be changed to an external reference. 


These editor-supplied external references, unless resolved with 
other input modules, cause the automatic library call mechanism 
to attempt to resolve them. Also, the deletion of a control 
section or an entry name may cause external references from 
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other input modules to be unresolved. Either condition can 
cause the output load module to be marked not executable. 


If a deleted control section contains an unresolved external 
reference, the reference remains. 


If a REPLACE statement, used to delete a CSECT, is the last 
control statement and there are external references to be 
resolved from SYSLIB, the delete request operates on the first 
module from SYSLIB and deletes it. The external reference 
remains unresolved. 


Note: When a control section is deleted, any CSECT 
identification data associated with that control section is also 
deleted. 


In the following example, control section CODER is to be deleted 
(Figure 20). 


//SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,UNIT=3350, 
// VOLUME=SER=PVT002 
//SYSLIN DD is 

ENTRY START1 


REPLACE CODER 
INCLUDE SYSLMODCCODEROUT ) 
NAME CODEROUTCR) 

7% 





Input Module JCL and Control Statements Output Load Module 
copEenoe CODEROUT 
//SY¥SLMOD DD DSNAME=PVTLIB,... 
ENCODE //SYSLIN DD * ENCODE 
ENTRY START 1 
REPLACE CODER 
INCLUDE SYSLMOD( CODEROUT ) 
—_> NAME CODEROUT(R ) DECODE 
/* 





DECODE 





Figure 20. Deleting a Control Section 


The control section CODER is deleted. If no address constants 

refer to CODER from other control sections in the module, the 

control section name is also deleted. If address constants 

refer to CODER, the name is retained as an external reference. ) 
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ORDERING CONTROL SECTIONS OR NAMED COMMON AREAS 


The sequence of control sections or named common areas 1n an 
output load module can be specified by using the ORDER control 
statement. 


Individual control sections or named common areas are arranged 
in the output load module according to the sequence in which 
they appear on the ORDER control statement. Multiple ORDER 
control statements can be used in a job step. The sequence of 
the ORDER statements determines the sequence of the control 
sections or named common areas in the load module. 


Any control sections or named common areas that are not 
specified on ORDER statements appear last in the output load 
module. If a control section or named common area is changed by 
a CHANGE or REPLACE control statement, the new name must be used 
on the ORDER statement. 


In the following example, ORDER statements are used to specify 
the sequence of five of the six control sections in an output 
load module. A REPLACE statement is used to replace the old 
control section, SESECTA, with the new control section, CSECTA, 
from the data set &&OBJECT, which was passed from a previous 
step. Assume that the control sections to be ordered are found 
in library member MAINROOT (CFigure 21 on page 56). 


//SYSLMOD DSNAME=PVTLIB,DISP=OLD, 

// UNIT=3350,VOLUME=SER=PVTO002 

//SYSLIN DSNAME=&&OBJECT, DISP=COLD,DELETE) 
% 


MAINEP,SEGMT1,SEG2 


SESECTACCSECTA) 
CSECTA,CSECTB 
SYSLMODCMAINROOT ) 
MAINROOT 
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Input Modules JCL and Control Statements Output Load Module 


&& OBJECT WMINROGH 
' as 
oer MAINEP 
PGM=HEWL 
// gua SEGMT1 
MAINROOT 
CSECTB : 
//SYSLMOD DD DSNAME=PVTLIB,... 
//SYSLIN DD DSNAME=&&OBJECT,... 
SESECTA J] DD * CSECTA 
ORDER MAINEP(P) ,SEGMTL ,SEG2 
REPLACE SESECTA(CSECTA) 
MAINEP CSECTB 
ORDER CSECTA,CSECTA, CSECTB (P) 
INCLUDE SYSLMOD (MAINROOT) 
LASTEP NAME MAINROOT LASTEP 
/* 


SEGMT1 





Figure 21. Ordering Control Sections 


In the load module MAINROOT, the control sections MAINEP, 
SEGMT1, SEG2, CSECTA, and CSECTB are rearranged in the output 
load module according to the sequence specified in the ORDER 
statements. A REPLACE statement 1s used to replace control 
section SESECTA with control section CSECTA from data set 
&&O0BJECT, which was passed from a previous step. The ORDER 
statement refers to the new control section CSECTA. Control 
section LASTEP appears after the other control sections in the 
output load module, because it was not included in the ORDER 
statement operands. 


ALIGNING CONTROL SECTIONS OR NAMED COMMON AREAS ON PAGE BOUNDARIES 


A control section or named common area can be placed on a page 
boundary (to effect a lower paging rate and thus make more 
efficient use of real storage) by using either the ORDER 
statement or the PAGE statement. 


The control section or common area to be aligned is named on 
either the PAGE statement or the ORDER statement with the P 
operand. Either the PAGE statement or the ORDER statement (Cwith 
the P operand) causes the linkage editor to locate the starting 
address of the control section or common area on a page boundary 
within the load module. 


In the following example, the control sections RAREUSE and 
MAINRT are aligned on page boundaries by PAGE and ORDER control 
statements. Control sections MAINRT, CSECTA, and SESECTI are 
sequenced by the ORDER control statement. Assume that each 
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control section, except for SESECT1 and RAREUSE, is 4K bytes in 
length (Figure 22). 


//LKED PGM=HEWL,PARM="...'° 


7/SYSLMOD DSNAME=OWNLIB,DISP=OLD,UNIT=3350, 
// 


VOLUME=SER=OWNO002 
//SYSLIN x 

RAREUSE 

MAINRTCP),CSECTA,SESECTI 

SYSLMOD CMAINROOT) 

MAINROOT 





Input Module JCL and Controls Statements Output Load Module 
MAINROOT MAINROOT 
OK 
CSECT 
: . / /UKED EXEC PGM=HEWL 
° 4K 
RAREUSE , CSECTA 
//SYSLMOD DD DSNAME=OWNLIB,... 
SESECT]| //SYSLIN DD i 
PAGE RAREUSE 8K 
BOTTOM ORDER MAINRT(P),CSECTA,SESECT1 | SESECTI 
INCLUDE SYSLMOD(MAINROOT) 
NAME MAINROOT 
7 12K 


RAREUSF 
MAINRT 


BOTTOM 





Figure 22. Aligning Control Sections on Page Boundaries 


The linkage editor places the control sections MAINRT and 
RAREUSE on page boundaries. Control sections MAINRT, CSECTA, 
and SESECT1 are sequenced as specified in the ORDER statement. 
RAREUSE, while placed on a page boundary, appears after the 
control sections specified in the ORDER statement because it was 
not included. The control section BOTTOM comes after RAREUSE 
because it appeared after RAREUSE in the input module. 
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OVERLAY PROGRAMS 


Ordinarily, when a load module produced by the linkage editor is 
executed, all the control sections of the module remain in 
virtual storage throughout execution. The length of the load 
module is, therefore, the sum of the lengths of all the control 
sections. When storage space is not at a premium, this is the 
most efficient way to execute a program. However, if a program 
approaches the limits of the virtual storage available, the 
programmer should consider using the overlay facilities of the 
linkage editor. 


In most cases, all that 15S needed to convert an ordinary program 
to an overlay program 1s the addition of control statements to 
structure the module. The programmer chooses the overlayable 
portions of the program, and the system arranges to load the 
required portions when needed during execution of the program. 


When the linkage editor overlay facility is requested, the load 
module is structured so that, at execution time, certain control 
sections are loaded only when referenced. When a reference is 
made from an executing control section to another, the system 
determines whether or not the code required is already in 
virtual storage. If it 15 not, the code is loaded dynamically 
and may overlay an unneeded part of the module already in 
storage. 


The rest of this chapter is divided into three sections that 
describe the design, specification, and special considerations 
for overlay programs. 


DESIGN OF AN OVERLAY PROGRAM 


The way in which an overlay module is structured depends on the 
relationships among the control sections within the module. Two 
control sections that do not have to be in storage at the same 


time can overlay each other. Such control sections are 
independent; that is, they do not reference each other either 
directly or indirectly. Independent control sections can be 


assigned the same load addresses and are loaded only when 
referenced. For example, control sections that handle error 
conditions or unusual data may be used infrequently, and need 
not be occupying storage unless in use. 


Control sections are grouped into segments. A segment is the 
smallest functional unit Cone or more control sections) that can 
be loaded as one logical entity during execution. The control 
sections required all the time are grouped into a special 
segment called the root seqment. This segment remains in 
storage throughout execution of an overlay program. 


When a particular segment is to be executed, any segments 
between it and the root segment must also be in storage. This 
is a path. A reference from one segment to another segment 
lower in a path is a downward reference (see "Control Section 
Dependency™ on page 59). That is, the segment contains a 
reference to another segment farther from the root segment. 
Conversely, a reference from one segment to another segment 
higher in a path (closer to the root segment) is an upward 


reference. 


Therefore, a downward reference may cause overlay, because the 
necessary segment may not yet be in virtual storage. An upward 
reference will not cause overlay, because all segments between a 
segment and the root segment must be present in storage. 


Sometimes several paths need the same control sections. This 
problem may be solved by placing the control sections in another 
region. In an overlay structure, a region is a contiguous area 
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of virtual storage within which segments can be loaded 
independently of paths in other regions. An overlay program can 
be designed in single or multiple regions. 


SINGLE REGION OVERLAY PROGRAM 


To design an overlay structure, the programmer should select 
those control sections that will receive control at the 
beginning of execution, plus those that should always remain in 
storage; these control sections form the root segment. The rest 
of the structure is developed by determining the dependencies of 
the remaining control sections and how they can use the same 
virtual storage locations at different times during execution. 


Besides control section dependency, other topics discussed in 
this section are segment dependency, the length of the overlay 
program, segment origin, communication between segments, and 
overlay processing. 


Control Section Dependency 


Control section dependency is determined by the requirements of 
a control section for a given routine in another control 


section. A control section is dependent upon any control 
section from which it receives control, or which processes its 
data. For example, if control section C receives control from 


control section B, then C is dependent upon B. That is, both 
control sections must be in storage before execution can 
continue beyond a given point in the program. 


Assume that a program contains seven control sections, CSA 

through CSG, and exceeds the amount of storage available for its 

execution. Before the program is rewritten, it is examined to 

see whether or not it could be placed into an overlay structure. 
| Figure 23 on page 60 shows the groups of dependent control 

ed sections in the program (the arrows indicate dependencies). 
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Figure 23. Control Section Dependencies 


Each dependent group is also a path. That is, if control 
section CSG is to be executed, CSB and CSA must also be in 
storage. Because CSA and CSB are in each path, they must be in 
the root segment. Control section CSC is in two groups, and 
therefore 1S a common segment in two different paths. 


A better way to show the relationship between segments 15 with a 
tree structure. A tree is the graphic representation that shows 
how segments can use virtual storage at different times. It 

does not imply the order of execution, although the root segment 
is the first to receive control. Figure 24 on page 61 shows the 
tree structure for the dependent groups shown in Figure 23. The 
structure is contained in one region, and has five segments. 
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Figure 24. Single-Region Overlay Tree Structure 


Seqment Dependency 


When a segment is in virtual storage, all segments in its path 
are also in virtual storage. Each time a segment is loaded, all 
segments in its path are loaded if they are not already in 
virtual storage. In Figure 24, when segment 3 1s in virtual 
storage, segments 1 and 2 are also in virtual storage. However, 
if segment 2 1s in storage, this does not imply that segment 3 


or 4 1s in virtual storage, because neither segment is in the 
path of segment 2. 


The position of the segments in an overlay tree structure does 
not imply the sequence in which the segments are executed. A 
segment can be loaded and overlaid as many times as required by 
the logic of the program. However, a segment will not be 
overlaid by itself. If a segment is modified during execution, 
that modification remains only until the segment is overlaid. 


: Length of an Overlay Program 


For purposes of illustration, assume that the control sections 
in the sample program have the following lengths: 
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If the program were not in overlay, it would require 32000 bytes 
of virtual storage. In overlay, however, the program requires 
the amount of storage needed for the longest path. In this 
structure, the longest path is formed by segments 1, 2, and 3, 
since, when they are all in storage, they require 18000 bytes, 
as shown in Figure 25. 
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Figure 25. Length of an Overlay Module 





J 


Note: The length of the longest path is not the minimum 
requirement for an overlay program; when a program is in 
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Segment Origin 


overlay, certain tables are used, and their storage requirements 
must also be considered. The storage required by these tables 
is given in the section "Special Considerations" on page 7/7. 


The linkage editor assigns the relocatable origin of the root 
segment (the origin of the program) at 0. The relative origin 
of each segment is determined by 0 plus the length of all 
segments in the path. For example, the origin of segments 3 and 
4 1s equal to 0 plus 6000 (the length of segment 2) plus 5000 
(the length of the root segment), or 11000. The origins of all 
the segments are as follows: 





The segment origin is also called the load point, because it is 
the relative location at which the segment is loaded. 


Figure 26 on page 64 shows the segment origin for each segment 
and the way storage is used by the sample program. In the 
illustration, the vertical bars indicate segment origin; any two 
segments with the same origin may use the same storage area. 
Figure 26 also shows that the longest path is that of segments 
1, 2, and 3. 
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64 


Segments that can be in virtual storage simultaneously are 
considered to be inclusive. Segments in the same region but not 
in the same path are considered to be exclusive; they cannot be 
in virtual storage simultaneously. Figure 27 on page 65 shows 
the inclusive and exclusive segments in the sample program. 
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Figure 27. Inclusive and Exclusive Segments 


Segments upon which two or more exclusive segments are dependent 
are called common seaments. A segment common to two other 
segments 15 part of the path of each segment. Figure 2/7, 
segment 2 18 common to segments 3 and 4, but not to segment 5. 


An inclusive reference is a reference between inclusive 
segments; that is, a reference from a segment in storage to an 
external symbol in a segment that will not cause overlay of the 
calling segment. An exclusive reference is a reference between 
exclusive segments; that is, a reference from a segment in 
storage to an external symbol in a segment that will cause 
overlay of the calling segment. 


Figure 28 on page 66 shows the difference between an inclusive 
reference and an exclusive reference; the arrows indicate 
references between segments. 


INCLUSIVE REFERENCES: Wherever possible, inclusive references 
should be used instead of exclusive references. Inclusive 
references between segments are always valid and do not require 
special options. When inclusive references are used, there is 
also less chance for error in structuring the overlay program 
correctly. 


EXCLUSIVE REFERENCES: An exclusive reference is made when the 
external reference in the requesting segment is to a symbol 
defined in a segment not in the path of the requesting segment. 
Exclusive references are either valid or invalid. 


An exclusive reference is valid only if there is also an 
inclusive reference to the requested control section ina 
segment common to both the segment to be loaded and the segment 
to be overlaid. The same symbol must be used in both the common 
segment and the exclusive reference. In Figure 28 on page 66, a 
reference from segment B to segment A is valid, because there is 
an inclusive reference from the common segment to segment A. 
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(An entry table in the common segment contains the address of 
segment A; the overlay does not destroy this table.) 





Segment A 


Figure 28. 


66 





Common Segment 


Segment B 


Exclusive 
Reference 


Inclusive and Exclusive References 


In the same illustration, a reference from segment A to segment 
B is invalid, because there 1s no reference from the common 
segment to segment B. A reference from segment A to segment B 
can be made valid by including, in the common segment, an 
external reference to the symbol used in the exclusive reference 
to segment B. 


Another way to eliminate exclusive references is to arrange the 
program so that the references that will cause overlay are made 
in a higher segment. For example, the programmer could 
eliminate the exclusive reference shown in Figure 28 by writing 
a new module to be placed in the common segment; the new 
module's only function would be to reference segment B. The 
code in segment A could then be changed to refer to the new 
module instead of to segment B. Control then would pass from 
segment A to the common segment, where the overlay of segment A 
by segment B would be initiated. 


If either valid or invalid exclusive references appear in the 
program, the linkage editor considers them errors unless one of 
the special options is used. These options are described later 
in this section (see "Special Considerations™ on page 77). 


Notes: 


1. During the execution of a program written in a higher level 
language such as FORTRAN, COBOL, or PL/I, an exclusive call 
results in abnormal termination of the program if the 
requested segment attempts to return control directly to the 
invoking segment that has been overlaid. 


2. If a program written in COBOL includes a segment that 
contains a reference to a COBOL class test or TRANSFORM 
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table, the segment containing the table must be either (1) 
in the root segment or (2) a segment that is higher in the 
same path than the segment containing the reference to the 
table. 


Overlay Process 


The overlay process 1s initiated during execution of a program 
only if a control section in virtual storage references a 


control section not in storage. The control program determines 
the segment that the referenced control section is in and, if 
necessary, loads the segment. When a segment is loaded, it 


overlays any segment in storage with the same relative origin. 
Any segments in storage that are lower in the path of the 
overlaid segment may also be overlaid. An exclusive reference 
can also cause segments higher in the path to be overlaid. Ifa 
control section in storage references a control section in 
another segment already in storage, no overlay occurs. 


The portion of the control program that determines when overlay 
is to occur is the overlay supervisor, which uses special tables 
to determine when overlay is necessary. These tables are 
generated by the linkage editor, and are part of the output load 
module. The special tables are the segment table and the entry 
table(€s). Figure 29 shows the location of the segment and entry 
tables in the sample program. 


SEGTAB 
CSA 
Root Segment | 
CSB 
ENTAB 
CSC 
Segment 2 CSG Segment 5 
ENTAB 
CSD CSF Segment 4 
{ Segment 3 
CSE 


Figure 29. Location of Segment and Entry Tables in an Overlay Module 
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Because the tables are present in every overlay module, their 
size must be considered when planning the use of virtual 
storage. The storage requirements for the tables are given in 
"Special Considerations™ on page 77. <A more detailed discussion 
of the segment and entry tables follows. 


SEGMENT TABLE: Each overlay program contains one segment table 
(SEGTAB); this table is the first control section in the root 
segment. The segment table contains information about the 
relationship of the segments and regions in the program. During 
execution, the table also indicates which segments are either in 
storage or being loaded, and other control information. 


ENTRY TABLE: Each segment that is not the last segment in a path 
may contain one entry table CENTAB); this table, when present, 
1s the last control section in a segment. 


When overlay will be required, an entry in the table is created 
for a symbol to which control is to be passed, provided (1) the 
symbol is used as an external reference in the requesting 
segment, and (2) the symbol is defined in another segment either 
lower in the path of the requesting segment, or in another 
region. An ENTAB entry is not created for any symbol already 
present in an entry table closer to the root segment Chigher in 
the path), or for a symbol defined higher in the path. CA 
reference to a symbol higher in the path does not have to go 
through the control program because no overlay is required.) 


If an external reference and the symbol to which it refers are 
in segments not in the same path but in the same region, an 
exclusive reference was made. If the exclusive reference 15 
valid, an ENTAB entry for the symbol is present in the common 
segment. Because the common segment is higher in the path of 
the requesting segment, no ENTAB entry is created in the 
requesting segment. When the reference is executed, control 
passes through the ENTAB entry in the common segment. That is, 
a branch to the location in the ENTAB entry causes the overlay 
supervisor to be called to load the needed segment or segments. 


If the exclusive reference is invalid, no ENTAB entry is present 
in the common segment. If the LET option is specified, an 
invalid exclusive reference causes unpredictable results when 
the program is executed. Because no ENTAB entry exists, control 
is passed directly to the relative address specified in the 
reference, even though the requested segment may not be in 
virtual storage. 


MULTIPLE REGION OVERLAY PROGRAM 


If a control section is used by several segments, it is usually 
desirable to place that control section in the root segment. 
However, the root segment can get so large that the benefits of 
overlay are lost. If some of the control sections in the root 
segment could overlay each other (except for the requirement 
that all segments in a path must be in storage at the same 
time), the job may be a candidate for multiple region structure. 
Multiple region structures can also be used to increase segment 
loading efficiency: Processing can continue in one region while 
the next path to be executed is being loaded into another 
region. 


With multiple regions, a segment has access to segments that are 
not in its path. Within each region, the rules for single 
region overlay programs apply, but the regions are independent 
of each other. A maximum of four regions can be used. 


Figure 30 on page 69 shows the relationship between the control 
sections in the sample program and two new control sections, CSH 
and CSI. The two new control sections are each used by two 
other control sections in different paths. Placing CSH and CSI 
in the root segment makes the segment larger than necessary, 
because CSH and CSI can overlay each other. The two control 
sections should not be duplicated in two paths, because the 
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Figure 30. 


linkage editor automatically deletes the second pair and an 
invalid exclusive reference may then result. 
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CSA 


CSB 


CSC 








Control Sections Used by Several Paths 


If, however, the two control sections are placed in another 
region, they can be in virtual storage when needed, regardless 
of the path being executed in the first region. Figure 31 on 
page 70 shows all the control sections in a two-region 
structure. Either path in region 2 can be in virtual storage 
regardless of the path being executed in region 13; segments in 
region 2 can cause segments in region 1 to be loaded without 
being overlaid themselves. 
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Figure 31. Overlay Tree for Multiple-Region Program 


The relative origin of a second region is determined by the 
length of the longest path in the first region (18000 bytes). 


Region 2, therefore, begins at 0 plus 18000 bytes. The relative 


origin of a third region would be determined by the length of 
the longest path in the first region plus the longest path in 
the second region. 


The virtual storage required for the program is determined by 
adding the lengths of the longest path in each region. In 
Figure 31, if CSH is 4000 bytes and CSI is 3000 bytes, the 
storage required 15 22000 bytes, plus the storage required by 
the special overlay tables. 


Care should be exercised when choosing multiple regions. There 
may be some system degradation caused by the overlay Supervisor 
being unable to optimize segment loading when multiple regions 
are used. 


SPECIFICATION OF AN OVERLAY PROGRAM 


Once the programmer has designed an overlay structure, the 
module must be placed in that structure by indicating to the 
linkage editor the relative positions of the segments and 
regions, and the control sections in each segment. Positioning 
is accomplished as follows: 
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SEGNENT ORIGIN 


e Segments are positioned by OVERLAY statements. Because 
segments are not named, the programmer identifies a segment 
by giving its origin Cor load point) a symbolic name and 
then uses that name in an OVERLAY statement to specify a 
symbolic origin. Each OVERLAY statement begins a new 
segment. 


e Regions are also positioned by OVERLAY statements. The 
programmer specifies the origin of the first segment of the 
region, followed by the word REGION in parentheses. 


e Control sections are positioned in the segment specified by 
the OVERLAY statement with which they are associated in the 
input sequence. However, the sequence of the control 
sections within a segment is not necessarily the order in 
which the control sections are specified. 


The input sequence of control statements and control sections 
should reflect the sequence of the segments in the overlay 
structure from top to bottom, left to right, and region by 
region. This sequence is illustrated in later examples. 


In addition, several special options are used with overlay 
programs. These options are specified on the EXEC statement for 
the linkage editor job step, and are described at the end of 
this section. 


Note: If a load module in overlay structure is to be 
reprocessed by the linkage editor, the OVERLAY statements and 
special options (such as OVLY) must be respecified. If the 
statements and options are not provided, the output load module 
will not be in overlay structure. 


The symbolic origin of every segment, other than the root 
segment, must be specified with an OVERLAY statement. The first 
time a symbolic origin is specified, a load point is created at 
the end of the previous segment. That load point is logically 
assigned a relative address at the doubleword boundary that 
follows the last byte in the preceding segment. Subsequent use 
of the same symbolic origin indicates that the next segment is 
to have its origin at the same load point. 


In the sample single-region program, the symbolic origin names 
ONE and TWO are assigned to the two necessary load points, as 
shown in Figure 31 on page 70. Segments 2 and 5 are at load 
point ONE; segments 3 and 4 are at load point TWO. 


The following sequence of OVERLAY statements will result in the 
structure in Figure 32 on page 72 (the control sections in each 
segment are indicated by name): 


Control section CSA 
Control section CSB 
OVERLAY ONE 
Control section CSC 
OVERLAY TWO 
Control section CSD 
Control section CSE 
OVERLAY TWO 
Control section CSF 
OVERLAY ONE 
Control section CSG 


Note: The sequence of OVERLAY statements reflects the order of 
segments in the structure from top to bottom and left to right. 
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Figure 32. Symbolic Segment Origin in Single-Region Program 


REGION ORIGIN 


The symbolic origin of every region, other than the first, must 
be specified with an OVERLAY statement. Once a new region is 
specified, a segment origin from a previous region should not be 
specified. 


In the sample multiple-region program, the symbolic origin THREE 


1S assigned to region 2, as shown in Figure 33 on page 73. 
Segments 6 and 7 are at load point THREE. 
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Figure 33. Symbolic Segment and Region Origin in Multiple-Region Program 





If the following is added to the sequence for the single-region 
program, the multiple-region structure will be produced: 


OVERLAY THREECREGION) 
Control section CSH 
OVERLAY THREE. 
Control section CSI 


POSITIONING CONTROL SECTIONS 


After each OVERLAY statement, the control sections for that 
segment must be specified. The control sections for a segment 
can be specified in one of three ways: 


° By placing the object decks for each segment after the 
appropriate OVERLAY statement 


° By using INCLUDE control statements for the modules 
containing the control sections for the segment 


° By using INSERT control statements to reposition a control 
section from its position in the input stream to a 
particular segment 


Any control sections that precede the first OVERLAY statement 


are placed in the root segment; they can be repositioned with an 
INSERT statement. Control sections from the automatic call 
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Using Object Decks 


library are also placed in the root segment. The INSERT 
statement can be used to place these control sections in another 
specific segment. Common areas in an overlay program are 
described in "Special Considerations” on page 77. 


An example of each of the three methods of positioning control 
sections follows. Each example results in the structure for the 
single-region sample program. An example is also given of 
repositioning control sections from the automatic call library. 


The primary input data set for this example contains an ENTRY 
statement and seven object decks, separated by OVERLAY 
statements: 


//LKED EXEC PGM=HEWL,PARM=‘OVLY' 


//SYSLIN DD 
ENTRY BEGIN. 
Object deck for 
Object deck for 
OVERLAY ONE. 
Object deck for 
OVERLAY TWO. 
Object deck for 
Object deck for 
OVERLAY TWO. 
Object deck for 
OVERLAY ONE. 
Object deck for 

7¥® 





The EXEC statement illustrates that the OVLY parameter must be 
specified for every overlay program to be processed by the 
linkage editor. 


Using INCLUDE Statements 


The primary input data set for this example contains a series of 
control statements. The INCLUDE statements in the primary input 
data set direct the linkage editor to library members that 
contain the control sections of the program. 


//LKED EXEC PGM=HEWL,PARM="OVLY' 


//MODLIB DD DSNAME=OBJLIB,DISP=COLD,KEEP),... 
//35YSLIN DD * 
ENTRY BEGIN 
INCLUDE MODLIBCCSA,CSB) 
OVERLAY ONE 
INCLUDE MODLIB(CSC) 
OVERLAY TWO 
INCLUDE MODLIBC(CSD,CSE) 
OVERLAY TWO 
INCLUDE MODLIBCCSF) 
OVERLAY ONE 
INCLUDE MODLIBCCSG) 
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This example differs from the previous one in that the control 
sections of the program are not part of the primary input data 
set, but are represented in the primary input by the INCLUDE 
statements. When an INCLUDE statement is processed, the 
appropriate control section is retrieved from the library and 
processed. 


Using INSERT Statements 


When INSERT statements are used, the INSERT and OVERLAY 
statements may either follow or precede all the input modules. 
However, the order of the control sections in a segment 1s not 
necessarily the same as the order of the INSERT statements for 
each segment. An example of each 1s given, as well as an 
example of repositioning automatically called control sections. 


FOLLOWING ALL INPUT: The control statements can follow all the 
input modules, as shown in the following example: 


//LKED EXEC PGM=HEWL,PARM='OVLY' 


//SYSLIN DD DSNAME=OBJECT,DISP=COLD,KEEP),... 
7 DD x 
ENTRY BEGIN 
INSERT CSA,CSB 
OVERLAY ONE 
INSERT CSC 
OVERLAY TWO 
INSERT CSD,CSE 
OVERLAY TWO 
INSERT CSF 
OVERLAY ONE 
INSERT CSG 





The primary input data set contains the object modules for the 
control sections, and the input stream is concatenated to it. 


PRECEDING ALL INPUT: The control statements can also precede all 
Input modules, as shown in the following example: 


//LKED EXEC PGM=HEWL,PARM="OVLY' 
//MODULES DD DSNAME=OBJSEQ,DISP=C(OLD,KEEP),... 


7SYSLIN DD 
ENTRY BEGIN 
INSERT CSA,CSB 
OVERLAY ONE 
INSERT CSC 
OVERLAY TWO 
INSERT CSD,CSE 
OVERLAY TWO 
INSERT CSF 
OVERLAY ONE 
INSERT CSG 
INCLUDE MODULES 
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SPECIAL OPTIONS 


OVLY Option 


The primary input data set contains all the control statements 
for the overlay structure and an INCLUDE statement. The data 
set specified by the INCLUDE statement contains all the object 
modules for the structure, and is a sequential data set. 


REPOSITIONING AUTOMATICALLY CALLED CONTROL SECTIONS: The INSERT 
statement can also be used to move automatically called control 


sections from the root segment to the desired segment. This is 
helpful when control sections from the automatic call library 
are used in only one segment. By moving such control sections, 


the root segment will contain only those control sections used 
by more than one segment. 


When a program 15 written in a higher level language, special 
control sections are called from the automatic call library. 
Assume that the sample program is written in COBOL and that two 
control sections CILBOVTRO and ILBOSCHO) are called 
automatically from SYS1.COBLIB. Ordinarily, these control 
sections are placed in the root segment. However, INSERT 
statements are used in the following example to place these 
control sections in segments other than the root segment. 


/7LKED EXEC PGM=HEWL,PARM='OVLY' 
//MODLIB DD DSNAME=OBJLIB,DISP=COLD,KEEP),... 
//7SYSLIB DD DSNAME=SYS1.COBLIB,DISP=SHR 


//SYSLIN DD x 
ENTRY BEGIN 
INCLUDE MODLIBCCSA,CSB) 
OVERLAY ONE 
INCLUDE MODLIBC(CSC) 
OVERLAY TWO 
INCLUDE MODLIBC(CSD,CSE) 
INSERT ILBOVTRO 
OVERLAY TWO 
INCLUDE MODLIB(CSF) 
INSERT ILBOSCHO 
OVERLAY ONE 
INCLUDE MODLIBC(CSG) 





As a result, segments 3 and 4 will also contain ILBOVTRO and 
ILBOSCHO, respectively. 


This example also combines two of the ways of specifying the 
control sections for a segment. 


The linkage editor provides three special job step options 
(COVLY, LET, and XCAL) for the overlay programmer. These options 
are specified on the EXEC statement for the linkage editor job 
step. They must be specified each time a load module itn overlay 
structure 1s reprocessed by the linkage editor. 


The OVLY option must be specified for every overlay program. If 
the option is omitted, all the OVERLAY and INSERT statements are 
considered invalid. Unless the LET option is specified, the 
output module is marked not executable. The output module is 
not in an overlay structure. 
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Cc 


LET Option 


XCAL Option 


With the LET option, the cutput module is marked executable even 
though certain error conditions were found during linkage editor 
processing. When LET 1s specified, any exclusive reference 
(valid or invalid) is accepted. At execution time, a valid 
exclusive reference is executed correctly; an invalid exclusive 
reference usually causes unpredictable results. 


Also with the LET option, unresolved external references do not 
prevent the module from being marked executable. This could be 
helpful when part of a large program is ready for testing; the 

segments to be tested may contain references to segments not yet 


coded. If LET is specified, the program can be executed to test 
those parts that are finished Cas long as the references to the 
absent segments are not executed). If the LET option is not 


specified, these unresolved references will cause the module to 
be marked not executable. 


With the XCAL option, a valid exclusive call is not considered 
an error, and the load module 15s marked executable. However, 
unless the LET option is specified, other errors could cause the 
module to be marked not executable. In this case, the XCAL 
option is not required. 


AMODE and RMODE Options 


If the OVLY option is specified, the AMODE and RMODE options are 
ignored and a diagnostic message 15 issued to that effect. 
Overlay programs are assigned a residence mode of 24 and an 
addressing mode of 24. 


SPECIAL CONSIDERATIONS 


COMMON AREAS 


This section discusses several special considerations that 
affect overlay programs. These considerations include the 
handling of common areas, special storage requirements, and 
overlay communication. 


When common areas (blank or named) are encountered in an overlay 
Program, the common areas are collected as described previously 
(that is, the largest blank or identically named common area 15 
used). The final location of the common area in the output 
module depends on whether INSERT statements were used to 
structure the program. 


If INSERT statements are used to structure the overlay program, 

a named common area should either be part of the input stream in 
the segment to which it belongs, or should be placed there with 

an INSERT statement. 


Because INSERT statements cannot be used for blank common areas, 
a blank common area should always be part of the input stream in 
the segment to which it belongs. 


If INSERT statements are not used, and the control sections for 
each segment are placed or included between OVERLAY statements, 
the linkage editor "promotes" the common area automatically. 
That is, the common area is placed in the common segment of the 
paths that contain references to it so that the common area is 
in storage when needed. The position of the promoted area in 
relation to other control sections within the common segment is 
unpredictable. 


If a common area 1s encountered in a module from the automatic 
call library, automatic promotion places the common area in the 
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root segment. In the case of a named common area, 


overridden by use of the INSERT statement. 


this may be 


Assume that the sample program is written in FORTRAN and that 


common areas are present as shown 1n Figure 34. 


Further assume 


that the overlay program is structured with INCLUDE statements 
between the OVERLAY statements so that automatic promotion 


occurs. 
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Figure 34. Common Areas before Processing 
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Segments 2 and 5 contain blank Common areas, 


Blank Common 


Segment 5 


segments 3 and 4 


contain named common area A, and segments 4 and 5 contain named 


common area B. During linkage editor processing, 
common areas are collected and the largest area 


the blank 
is promoted to 


the root segment (the first common segment in the two paths); 
the common areas named A are collected and the largest area is 
promoted to segment 2; the common areas named B are collected 
and promoted to the root segment. Figure 35 on page 79 shows 
the location of the common areas after processing by the linkage 


editor. 
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Figure 35. Common Areas after Processing 


STORAGE REQUIREMENTS 


The virtual storage requirements for an overlay program include 
the items placed in the module by the linkage editor and the 
overlay supervisor necessary for execution. 


ITEMS IN THE LOAD MODULE: The items that the linkage editor 
places in an overlay load module are the segment table, entry 
tables, and other control information. Their size must be 
included in the minimum requirements for an overlay program, 
along with the storage required by the longest path and any 
control sections from the automatic call library. 


Every overlay program has one segment table in the root segment. 
The storage requirements are: 


SEGTAB = &n + 24 


where: 


n the number of segments in the program 

Some segments Will have an entry table. The requirements of the 
entry tables in the segments in the longest path must be added 
to the storage requirements for the program. The requirements 
for an entry table are: 
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ENTAB = 1l2(x + 1) 


where: 
x = the number of entries in the table 


Finally, a NOTE list is required to execute an overlay program. 
The storage requirements are: 


NOTELST = 4n + 8 


where: 
n = the number of segments in the program 


OVERLAY SUPERVISOR: To the minimum requirements of the load 
module itself must be added the requirements of the overlay 
supervisor. This system routine is not placed in an overlay 
module, but, during execution of the module, the supervisor may 
be called to initiate an overlay. If called, the storage 
allocated for the program must also be large enough for the 
supervisor. 


This asynchronous overlay supervisor module is furnished with 


the system. This asynchronous module also permits overlay 
through the SEGLD macro instruction (see "Overlay 
Communication”). The storage requirement for the overlay 


supervisor module is 180 bytes. 


OVERLAY COMMUNICATION 


Several ways of communicating between segments of an overlay 
Program are discussed in this section. A higher level or 
Assembler language program may use a CALL statement or a CALL 
macro instruction, respectively, to cause control to be passed 
to a symbol defined in another segment. The CALL may cause the 
segment to be loaded if it is not already present in storage. 

An Assembler language program may also use three additional ways 
to communicate between segments: 


° By a branch instruction, which causes a segment to be loaded 
and control to be passed to a symbol defined in that 
segment. 

e By a segment load (SEGLD) macro instruction, which requests 


loading of a segment. Processing continues in the 
requesting segment while the requested segment is being 
loaded. 


e By a segment load and wait (SEGWT) macro instruction, which 
requests loading of a segment. Processing continues in the 
requesting segment only after the requested segment is 
loaded. 


Any of the four methods may be used to make inclusive 
references. Only the CALL and branch may be used to make 
exclusive references. Neither the SEGLD nor the SEGWT macro 
instruction should be used to make exclusive references; because 
both imply that processing is to continue in the requesting 
segment, an exclusive reference leads to erroneous results when 
the program is executed. 


CALL Statement or CALL Macro Instruction 


80 


A CALL statement or a CALL macro instruction refers to an 
external name in the segment to which control is to be passed. 
The external name must be defined as an external reference in 
the requesting segment. In Assembler language, the name must be 
defined as a 4¢-byte V-type address constant; the high-order bit 
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Branch Instruction 


is reserved for use by the control program, and must not be 
altered during execution of the program. 


When a CALL is used, the requested segment and any segments in 
its path are loaded if they are not part of the path already in 
virtual storage. After the segment is loaded, control is passed 
to the requested segment at the location specified by the 
external name. 


A CALL between inclusive segments is always valid. A return can 
be made to the requesting segment by another source language 
statement, such as RETURN. A CALL between exclusive segments is 


valid if the conditions for a valid exclusive reference are met; 
a return from the requested segment can be made only by another 
exclusive reference, because the requesting segment has been 
overlaid. 


Any of the branching conventions shown in Figure 36 on page 82 
can be used to request loading and branching to a segment. Asa 
result, the requested segment and any segments in its path are 
loaded if they are not part of the path already in virtual 
storage. Control is then passed to the requested segment at the 
location specified by the address constant placed in general 
register 15. 
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Example Namet Operation Operand?¢, # ) 


1 L R15,=VCname) 
BALR Rn,R15 
2 L R15,ADCON 
BALR Rn,R15 
ADCON DC VCname) 
3 L R15,=V(Cname) 
BAL Rn,0(€0,R15)4 
4 L R15,=V(name) 
BAL Rn,OCR1L5)5 
56 L R15,=V(Cname) 
BCR 15,R15 
6° L R15,=VCname) 
BC 15,0€0,R15)4 
76 L R15,=VCname) 
BC 15,0C€R15)5 


Figure 36. Branch Sequences for Overlay Programs 


Notes to Figure 36: ) 


1 When the name field is blank, specification of a name is 
optional. 


2 R15 must hold a 4-byte address constant that is the address 
of an entry name or a control section name in the requested 
segment. The address constant must be loaded into the 
standard entry point register, register 15. 


> Rn is any other register and is used to hold the return 
address. This register is usually register 14. 


4 This may also be written so that the index register is loaded 
with the address constant; the other fields must be zero. 


5 In this format, the base register must be loaded with the 
address constant; the displacement must be zero. 


This example is an unconditional branch; other conditions are 
also allowed. 


The address constant must be a 4-byte V-type address constant. 
The high-order bit 1s reserved for use by the control program, 
and must not be altered during execution of the program. 


A branch between inclusive segments is always valid; a return 
may be made by means of the address stored in Rn. A branch 
betweeen exclusive segments is valid if the conditions for a 
valid exclusive reference are met; a return can be made only by 
another exclusive reference. 


Segment Load (SEGLD) Macro Instruction 
The SEGLD macro instruction is used to provide overlap between J 


segment loading and processing within the requesting segment. 
As a result of using any of the examples in Figure 37, the 
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loading of the requested segment and any segments in its path is 
initiated when they are not part of the path already in virtual 


storage. Processing then resumes at the next sequential 
instruction in the requesting segment while the segment or 
segments are being loaded. Control may be passed to the 
requested segment with either a CALL or a branch, as shown in 
Examples 1 and 2, respectively. A SEGWT instruction can be used 


to ensure that the data in the control section specified by the 
external name is in virtual storage before processing resumes, 
as shown in Example 3. 


Example Namel Operation Operandé, 4 


1 SEGLD external name 
CALL external name 

2 SEGLD external name 
branch external name 

3 SEGLD external name 
SEGNT external name 
L Rn,=VCname) 


Figure 37. Use of the SEGLD Macro Instruction 


Notes to Figure 37: 


1 When the name field is blank, specification of a name is 
optional. 


External name is an entry name or a control section name in 
the requested segment. 


> Rn is any other register and is used to hold the return 
address. This register is usually register 14. 


The external name specified in the SEGLD macro instruction must 
be defined with a 4¢-byte V-type address constant. The 
high-order bit is reserved for use by the control program and 
must not be altered during execution of the program. 


Segment Wait (SEGNT) Macro Instruction 


The SEGWNT macro instruction is used to stop processing in the 
requesting segment until the requested segment is in virtual 
storage. 


As a result of using any of the examples in Figure 38 on page 
84, no further processing takes place until the requested 
segment and all segments in its path are loaded when not already 
in virtual storage. Processing resumes at the next sequential 
instruction in the requesting segment after the requested 
segment has been loaded. 
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Example Namel Operation Operandé-, 4 


L SEGLD external name 
SEGWT external name 
L Rn, ADCON 
branch 
ADCON DC VCname) 
2 SEGWT external name 
L Rn, =VCname) 


Figure 38. Use of the SEGNT Macro Instruction 


Notes to Figure 38: 


1 When the name field is blank, specification of a name is 
optional. 


External name is an entry name or a control section name in 
the requested statement. 


> Rn is any other register and is used to hold the return 
address. This register is usually register 14. 


If the SEGWT and SEGLD macro instructions are used together, 
overlap occurs between processing and segment loading; use of 
the SEGWNT macro instruction serves as a check to see that the 
necessary information is in storage when it is finally needed 
(see Example 1 in Figure 38). In Example 2 in Figure 38, no 
overlap is provided; the SEGNT macro instruction initiates 
loading, and processing is stopped in the requesting segment 
until the requested segment is in virtual storage. 


The external name specified in the SEGWT macro instruction must 
be defined with a ¢-byte V-type address constant. The 
high-order bit is reserved for use by the control program, and 
must not be altered during execution of the program. 


If the contents of a virtual storage location in the requested 


segment are to be processed, the entry name of the location must 
be referred to by an A-type address constant. 
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EXEC STATEMENT——JOB 


JOB CONTROL LANGUAGE SUMMARY 


This chapter summarizes those aspects of the job control 
language that pertain directly to the use of the linkage editor. 
The major topics covered are the EXEC statement, DD statements, 
and cataloged procedures for the linkage editor. The reader 
should be familiar with the job control language as described in 
the publication JCL. 


EXEC STATEMENT—"INTRODUCTION 


The EXEC statement is the first statement of every job step. 
For the linkage editor job step, the following topics are 
pertinent: 

° The program name of the linkage editor 

® Linkage editor options passed to the job step 


° Region-size requirements for the linkage editor 


For an execution job step following the linkage editor job step, 
the linkage editor return code is important. 


The EXEC statement contains the symbolic name of the load module 


to be invoked for execution. The linkage editor can be invoked 
with the following program name: 
HEWL 


LINKEDIT is an alias name for the linkage editor and can also be 
used to invoke it. 


For example, the following EXEC statement causes the linkage 
editor to be invoked: 


//LKED EXEC PGM=HEWL 

PGM=LINKEDIT could also be used. 

To ensure compatibility with the operating system, the linkage 
editor can also be invoked by any of the following alias names: 
IEWL, IEWLF4¢4¢0, IEWLF&880, and IEWLF128. 

STEP OPTIONS 


The EXEC statement also contains a list of options or parameters 


to be passed to the linkage editor. These options are of four 
types: 
e Module attributes, which describe the characteristics of the 


output load module 


e Special processing options, which affect linkage editor 
processing 


Space allocation options, which affect the amount of storage 
used by the linkage editor for processing and output module 
library buffers 


e Output options, which specify the kind of output the linkage 
editor is to produce 


The rest of this section describes the options in each category. 
All the options for a particular linkage editor execution are 
listed in the PARM parameter on the EXEC statement. They can be 
listed in any sequence, as long as the rules for coding 
parameters are followed. 
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MODULE ATTRIBUTES 


The module attributes describe the characteristics of the output 
module, or modules. (If more than one load module is produced 
by the same linkage editor job step, all output modules will 
have the attributes assigned on the EXEC statement.) The 
attributes for each load module are stored in the directory of 
the output module library along with the member name. (The 
format of the directory entry of a partitioned data set 1s given 
in Data Areas.) 


Module attributes specify whether or not the module: 
e Can ever be processed by the linkage editor 


® Can be brought into virtual storage only by the LOAD macro 
instruction 


° Is to be in overlay format 

° Can be reused 

e Can be placed in the link pack area; that is, 1s reenterable 
e Can be replaced during execution by recovery management; 


that is, 1s refreshable 
® Is to be tested by the TSO TEST command 


e Is to have specified control sections aligned on page 
boundaries 


e Is or 1s not authorized to use the restricted system 
resources and functions 


After the descriptions of the module attributes, the default and 
incompatible attributes are discussed. 


Scatter Format Attribute 


When the scatter format attribute is specified, the linkage 
editor produces a load module ina format suitable for either 
scatter or block loading. 


To assign the scatter format attribute, code SCTR in the PARM 
field, as follows: 


//LKED EXEC PGM=IEWL,PARM="SCTR,...' 
Notes: 


1. If scatter format is not specified, the block format 
attribute 1s assigned by the linkage editor. (The 
programmer cannot specify block format. ) ; 


2. If SCTR is specified, the programmer should ensure that the 
load module does not contain zero-length control sections, 
private code sections, or common areas. The presence of 
such sections in a module that is to be scatter loaded can, 
under certain circumstances, cause the module to be loaded 
incorrectly. 


3. The SCTR attribute must be specified when the nucleus for a 
VS system is link-edited. In all other instances, if the 
SCTR attribute is specified, the linkage editor builds the 
output load module appropriately; however, scatter load 
support is not provided in VS systems and the attribute/load 
module format is ignored when fetching the load module. 
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Not Editable Attribute 


A load module which is marked NE (not editable) is not 
reprocessable by the linkage editor. If a module map or a 
cross-reference table is requested, the not-editable attribute 
15 ignored. 


To assign the not-editable attribute, code NE in the PARM field, 
as follows: 


//LKED EXEC PGM=HEWL,PARM="NE,...' 


Note: The not-editable attribute disables the EXPAND function 
for the output load module and also limits to 18 the number of 
consecutive iterations of AMASPZAP. If the EXPAND function 15 
required or more than 18 iterations of AMASPZAP are required, 
the load module must be re-created. 


Only-Loadable Attribute 


Overlay Attribute 


A module with the only-loadable attribute can be brought into 
virtual storage only with a LOAD macro instruction. Some 
subsets of the control program use a smaller control table when 
the load module is invoked with a LOAD. This reduces the 
overall virtual storage requirements of the module. 


The module with the only-loadable attribute must be entered by 
means of a branch instruction or a CALL macro instruction. If 
an attempt 1s made to enter the module with a LINK, XCTL, or 
ATTACH macro instruction, the program making the attempt 15 
terminated abnormally by the control program. 


To assign the only-loadable attribute, code OL in the PARM field 
as follows: 


//LKED EXEC PGM=HEWL,PARM="OL,...' 


A program with the overlay attribute is placed in an overlay 
structure as directed by linkage editor OVERLAY control 
statements. The module is suitable only for block loading; it 
cannot be refreshable, reenterable, or serially reusable. 


If the overlay attribute is specified and no OVERLAY control 
statements are found in the linkage editor input, the attribute 
1s negated. The condition 1s considered a recoverable error; 
that is, if the LET option is specified, the module is marked 
executable. 


The overlay attribute must be specified for overlay processing. 
If this attribute is omitted, the OVERLAY and INSERT statements 
are considered invalid, and the module is not an overlay 
structure. This condition 18S also recoverable; if the LET 
option 18s specified, the module is marked executable. 


To assign the overlay attribute, code OVLY in the PARM field as 
follows: 


//LKED EXEC PGM=HEWL,PARM='OVLY,...° 


See "Overlay Programs” on page 58 for information on the design 
and specification of an overlay structure. 


Reusability Attributes 


Either one of two attributes may be specified to denote the 
reusability of a module. (Reusabrlity means that the same copy 
of a load module can be used by more than one task either 
concurrently or one at a time.) The reusability attributes are 
reenterable and serially reusable; if neither is specified, the 
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module is not reusable and a fresh copy must be brought into 
virtual storage before another task can use the module. 


The linkage editor only stores the attribute in the directory 
entry; it does not check whether the module is really 
reenterable or serially reusable. A reenterable module is 
automatically assigned the reusable attribute. However, a 
reusable module is not also defined as reenterable; it is 
reusable only. 


REENTERABLE: A module with the reenterable attribute can be 
executed by more than one task at a time; that is, a task may 
begin executing a reenterable module before a previous task has 
finished executing it. This type of module cannot be modified 
by itself or by any other module during execution. 


If a module is to be reenterable, all the control sections 
Within the module must be reenterable. If the reenterable 
attribute is specified, and any load modules that are not 
reenterable become a part of the input to the linkage editor, 
the attribute is negated. 


To assign the reenterable attribute, code RENT in the PARM 
field, as follows: 


//LKED EXEC PGM=HEWL,PARM="RENT,...° 


SERIALLY REUSABLE: A module with the serially reusable attribute 
can be executed by only one task at a time; that is, a task may 
not begin executing a serially reusable module before a previous 
task has finished executing it. This type of module must 
initialize itself and/or restore any instructions or data in the 
module altered during execution. 


If a module is to be serially reusable, all its control sections 
must be either serially reusable or reenterable. If the 
serially reusable attribute is specified, and any load modules 
that are neither serially reusable nor reenterable become a part 
of the input to the linkage editor, the serially reusable 
attribute is negated. 


To assign the serially reusable attribute, code REUS in the PARM 
field, as follows: 


//LKED EXEC PGM=HEWL,PARM="REUS,...° 


Refreshable Attribute 


Test Attribute 


A module with the refreshable attribute can be replaced by a new 
copy during execution by a recovery management routine without 
changing either the sequence or results of processing. This 
type of module cannot be modified by itself or by any other 
module during execution. The linkage editor only stores the 
attribute in the directory entry; it does not check whether the 
module is refreshable. 


If a module is to be refreshable, all the control sections 
within it must be refreshable. If the refreshable attribute is 
specified, and any load modules that are not refreshable become 
a part of the input to the linkage editor, the attribute is 
negated. 


To assign the refreshable attribute, code REFR in the PARM 
field, as follows: 


//LKED EXEC PGM=HEWL,PARM="REFR,...' 


A module with the test attribute is to be tested and contains 
the testing symbol tables for the TSO TEST command. The linkage 
editor accepts these tables as input, and places them in the 
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Authorization Code 


output module. The module is marked as being under test. If 
the test attribute is not specified, the symbol tables are 
ignored by the linkage editor and are not placed in the output 
module. If the test attribute is specified, and no symbol table 
Input is received, the output load module will not contain 
symbol tables to be used by the TSO TEST command. 


To assign the test attribute, code TEST in the PARM field, as 
follows: 


//LKED EXEC PGM=HEWL,PARM='"TEST,...' 


Note: The test attribute applies to programs using either 
TESTRAN or the TSO TEST command. Do not use the ‘TEST’ option 
unless the load module is to be executed by either TSO or 
TESTRAN. 


The output load module is assigned an authorization code that 
determines whether or not the load module may use restricted 
system services and resources. 


To assign an authorization code through the PARM field, code the 
AC parameter as follows: 


//LKED EXEC PGM=HEWL,PARM="AC=n,...' 


The authorization code, n, must be 1 to 3 decimal digits with a 
value from 0 to 255. 


"AC=,...°" and 'AC= * are equivalent to 'AC=0'. The 
authorization code assigned in the PARM field is overridden by 
an authorization code assigned through the SETCODE control 
statement. 


Addressing Mode Attribute 


To assign the addressing mode for all the entry points into the 
load module (the main entry point, its true aliases, and all the 
alternate entry points), code the AMODE parameter as follows: 


//LKED EXEC PGM=IEWL, 
PARM="AMODE=xxx,...!' 


The addressing mode 'xxx' must be either 24, 31, or ANY. 


The addressing mode assigned in the PARM field overrides the 
separate addressing modes found in the ESD data for the control 
sections or private code where the entry points are located. 
The addressing mode assigned in the PARM field is overridden by 
an addressing mode assigned in the MODE control statement. 


If the AMODE parameter occurs more than once in the PARM field 
of the EXEC statement, the last valid parameter is used. 


If only the AMODE value is specified in the PARM field of the 
EXEC statement, an RMODE value of 24 is implied. 


Note: The keyword 'AMODE' may also be specified as 'AMOD'. 


Residence Mode Attribute 


To assign the residence mode for the output load module, code 
the RMODE parameter as follows: 


//LKED EXEC PGM=IEWL, 
PARM="RMODE=xxx,...' 


The residence mode 'xxx' must be either 24 or ANY. 
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The residence mode assigned in the PARM field overrides the 
residence mode accumulated from the input control sections and 
private code. The residence mode assigned in the PARM field is 
overridden by a residence mode assigned through the MODE control 
statement. 


If the RMODE parameter occurs more than once in the PARM field 
of the EXEC statement, the last valid parameter is used. 


If only an RMODE value of ANY is specified in the PARM field of 
the EXEC statement, an AMODE value of 31 is implied. 


If only an RMODE of 24 1s specified, no overriding AMODE value 
1s assigned; instead, the AMODE value in the ESD data for the 
main entry point, a true alias, or an alternate entry point is 
used in generating its respective directory entry. If any 
control section to be linked has an RMODE=24, then the load 
module 1s marked RMODE=24. 


Note: The keyword '"RMODE' may also be specified as 'RMOD'. 


Combinations of Addressing Mode and Residence Mode 


Default Attributes 


In generating a directory entry for the main entry point, a true 
alias, or an alternate entry point, the linkage editor validates 
the combination of the AMODE value and the RMODE value, as 
specified by the user in the PARM field of the EXEC statement, 
according to the following table: 


[ranean 
Panooe=si [varie | vette 


If the AMODE/RMODE combination resulting from the PARM field of 
the EXEC statement is invalid, an error message 1s issued and 
the linkage editor ignores the PARM field of the EXEC statement 
as the source of AMODE/RMODE data. 














Unless specific module attributes are indicated by the 
programmer, the output module is not in an overlay structure, 
and it 1s not tested. The module is in block format, not 
refreshable, not reenterable, and not serially reusable. If 
page boundary alignment is requested, its control sections are 
aligned on 4K-byte page boundaries. 


One other attribute is specified by the linkage editor after 
processing is finished. If, during processing, severity 2 
errors were found that would prevent the output module from 
being executed successfully, the linkage editor assigns the 
not-executable attribute. The control program will not load a 
module with this attribute. 


If the LET option is specified, the output module is marked 
executable even if severity 2 errors occur. (The LET option is 
discussed later in this section.) 


If the AC parameter 15 not specified or is coded incorrectly, 
the default authorization code of 0 is assigned to the output 
load module. 
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Incompatible Attributes 


Of the module attributes the programmer may specify, several are 
mutually exclusive. When mutually exclusive attributes are 
specified for a load module, the linkage editor ignores the 
less-significant attributes. For example, if both OVLY and RENT 
are specified, the module will be in an overlay structure and 
will not be reenterable. 


Certain attributes are also incompatible with other job step 
options. All job step options are shown in Figure 41 on page 99 
along with those options that are incompatible. 


SPECIAL PROCESSING OPTIONS 


The special processing options affect the executability of the 
output module and the use of the automatic library-call 
mechanism. These options are the exclusive call option, the let 
execute option, and the no automatic-call option. 


Exclusive Call Option 


Let Execute Option 


When the exclusive call option is specified, valid exclusive 
references have been made between segments, and the linkage 
editor marks the output module as executable. However, a 

warning message 1s given for:each valid exclusive reference. 


To specify the exclusive call option, code XCAL in the PARM 
field as follows: 


//LKED EXEC PGM=HEWL,PARM='XCAL,OVLY,...° 


The OVLY attribute must also be specified for an overlay 
program. 


Note: Unless the let execute option is specified, other errors 
may cause the module to be marked not executable. 


When the let execute option is specified, the linkage editor 
marks the output module as executable even though a severity 2 
error condition was found during processing. (A severity 2 
error condition could make execution of the output load module 
impossible.) Some examples of severity 2 errors are: 


e Unresolved external references 
e Valid or invalid exclusive calls in an overlay program 
e Error ona linkage editor control statement 


e A library module that cannot be found 


e No available space in the directory of the output module 
library 


To specify the let execute option, code LET in the PARM field as 
follows: 


//LKED EXEC PGM=HEWL,PARM='"LET,...'° 
Note: If LET is specified, XCAL need not be specified. 


No Automatic Library-Call Option 


When the no automatic library-call option is specified, the 
linkage editor library-call mechanism does not call library 
members to resolve external references. The output module is 
marked executable even though unresolved external references are 
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present. If this option is specified, the LIBRARY statement 
need not be used to negate the automatic library call for 
selected external references. Also, with this option, a SYSLIB 
DD statement need not be supplied. 


To specify the no automatic library-call option, code NCAL in 
the PARM field, as follows: 


//LKED EXEC PGM=HEWL,PARM="NCAL,...' 


Note: Unless the LET option is also specified, other errors may 
cause the module to be marked not executable. 


SPACE ALLOCATION OPTIONS 


SIZE Option 


These options allow the programmer to specify the storage 
available to the linkage editor, and to specify the block size 
for the output module. For large modules and SMP, see System 
Modification Program (SMP) System Programmers Guide. 


The programmer can specify, through the SIZE option, the amount 
of virtual storage to be used by the linkage editor and the 
portion of that storage to be used as the load module buffer. 


The linkage editor provides default values for the SIZE option. 
The default values are used if one or both of the values are not 
specified correctly by the user or are not specified at all. 
These defaults should be adequate for most link-edits, relieving 
the programmer from specifying the SIZE option for each 
link-edit. The default values are: valuel is 256K bytes and 


value2 is 48K bytes. 


FORMAT: The format of the SIZE option is: 
SIZE=(valuel,value2) 

SIZE=(valuel ) 

SIZE=(valuel, ) 

SIZE=(,value2) 

SIZE=(, ) 


When coded in the PARM field, valuel and value2 parameters are 
enclosed in parentheses as follows: 


//LKED EXEC PGM=HEWL, 
47 PARM="SIZE=(valuel,value2),...' 


Both valuel and value2 may be expressed as integers specifying 
the number of bytes of virtual storage or as nK, where n 
represents the number of 1K (1024) bytes of virtual storage. 


When determining the values for the SIZE option, it is best to 
establish value2 first, then valuel. 


VALUE2: Value2 specifies the number of bytes of storage to be 
allocated as the load module buffer. The allocation specified 
by value2 is a part of the virtual storage specified by valuel. 


The actual minimum for value2 is 6144 (6K) or the length of the 
largest input load module text record, whichever is larger. 
AMBLIST may be used to find the size of the load module text 
records. If a value less than 6144 (6K) is specified, the 
default value of 48K for value2 is used. 


The space allocated by value2 is used for: the buffer into which 
the input load module text is read, the buffer from which load 
module text is written to the intermediate data set, the buffer 
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into which the load module text is read from the intermediate 
data set, and the buffers from which the load module text is 
written to the output data set. Therefore, the determination of 
value2 requires that the programmer consider the record sizes of 
the data sets from which any load module text records are to be 
read (SYSLIB, any data set referenced by an INCLUDE, any library 
data set), the record size for the intermediate data set 
(SYSUT1), and the record size for the output load module data 
set (SYSLMOD). 


Figure 39 lists the direct access devices that may contain data 
sets that are the source of input load module text, the 
intermediate data set, and the output load module data set, and 
lists the maximum record size used for each device by the 
linkage editor. These maximum record sizes may always be used 
in specifytng value2 or, if the programmer can determine them, 
exact sizes can be used. 


Device Device Maximum SYSUT1 or SYSLMOD 
Record Size Maximum Record Size 
(Bytes ) (K Bytes) 

2305-1 14136 13 

2305-2 14660 14 

2314 7294 6 

2319 7294 6 

3330-1 13030 12 

3330-11 130%¢C 12 

3340 8368 8 

3344 8368 8 

3350 19069 18 

3375 32760 18 

3380 32760 18 


Figure 39. SYSUT1 and SYSLMOD Device Types and Their Maximum 
Record Sizes 


The programmer must specify value2 so that the linkage editor 
has sufficient space to allocate buffers that are compatible 
With the record sizes for the intermediate data set and the 
output load module data set. 


The linkage editor optimizes the record size for the device type 
of output load module data set unless one of the following 
conditions exists. 


1. The programmer has specified PARM="...DCBS,...", and the 
SYSLMOD DD statement contains a BLKSIZE subparameter in the 
DCB parameter, forcing the linkage editor to write records 
having a maximum length equal to the BLKSIZE specification. 


2. The output load module data set is an existing data set 
having a block size less than the optimum record size, 
forcing the linkage editor to write records no longer than 
that block size. 


3. The programmer has specified a value? less than twice the 
maximum record size for the output load module data set, 
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forcing the linkage editor to write records having a maximum 
size of one-half valued. : 
4. The intermediate data set and the output load module data 

set have dissimilar record sizes, forcing the linkage editor 

to write records having a maximum size determined for 

compatibility between the two data sets. 


The linkage editor optimizes the record size of the output load 
module data set for its device type but selects a record size 
compatible with the intermediate data set (see restrictions 
above). Therefore, if the intermediate data set and the output 
load module data set reside on the same device type, use of the 
load module buffer is optimized. Also, if the data sets are on 
different units of the same type, the performance of the linkage 
editor is improved. 


Figure 40 shows the record sizes used for compatibility between 


every combination of device types for the intermediate and 
output load module data sets. 


SYSUTL Record Size 


SYSLMOD Record Size 


Minimum 
Load Module 
Buffer Area 
(Value2) 


Maximum 
Record 
$1ze 
Produced 


Maximum 
Record 
size 
Produced 


Device 
Used 


Device 
Used 


IBM 
IBM 


Figure 
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2305-1 13K 
2305-1/-2 12K! 
12K! 
12K! 
2305-1 13K 


2305-2 


2314 
2319 


3330 
3330-11 


3350 
3375/3380 


2305-1,2305-2 
2314,2319 
3330,3330-11 
3340 
3350,3375,3380 
3350,3375,3380 


2305-1,2305-2 
2314,2319 
3330,3330-11 
3340 
3350,3375,3380 


2305-1,2305-2 
2314,2319 
3330,3330-11 
3340 
3350,3375,3380 


2305-1,2305-2 
2314,2319 
3330,3330-11 
3340 
3350,3375,3380 


2305-1 

2305-2 
2314,2319 
3330,3330-11 
3340 
3350,3375,3380 


13K 


26K 
24K 
24K 
24K 
26K 
28K 


12K 
12K 
12K 
12K 
18K 


24K 
24K 
24K 
24K 
24K 


14K 
12K 
12K 
16K 
16K 


26K 
28K 
36K 
24K 
36K 





G40. Load Module Buffer Area and SYSLMOD and SYSUT1 Record 


Sizes 


and Loader 


Notes to Figure 40: 


1 The SYSLMOD record size is reduced to less than the maximum 
to make it compatible with the SYSUTI1 record size. 


2 The SYSUTL record size is reduced to less than the maximum to 
to make 1t compatible with the SYSLMOD record size. 


Value2 should be, minimally, twice the record size for the 
output load module data set. If value? can be made larger than 
twice the record size for the output load module data set, the 
Increase should be the larger of the record sizes for the 
intermediate and output load module data sets. 


The practical maximum for value2 is the length of the load 
module to be built, plus 4K bytes if the length of the load 
module to be built is equal to or greater than 40960 (40K). Any 
space allocated to the load module buffer above this amount is 
not used and does not need be allocated to value2. 


If a value2 1s specified that cannot be accommodated in the 
available storage, value2 1s reduced to the next lower 2K-byte 
multiple of storage that is available. This reduction, however, 
never decreases value2 to less than the minimum, 6144 (6K). 


The optimal value2 is the practical maximum, as explained above. 
If the entire load module is contained in storage, the 
performance of the linkace editor is improved and the use of the 
intermediate data set may be eliminated. 


Examples of Value2 Determination 


1. <A load module of between 21K and 22K bytes is to be built. 
The load module data set 1s a new data set on an IBM 3330 
Disk Storage device. The intermediate data set is allocated 
to an IBM 3340 Direct Access Storage device. A SYSLIB data 
set is to be used, residing on a 3330. The entire load 
module could be contained in the load module buffer if 
value2 were 22K bytes (the load module size). The practical 
minimum for value2 would be 12K bytes (the size of the 
largest possible input load module text record from the 
SYSLIB data set). However, value2 should be at least as 
large as two records to be written to the load module data 
set (that is, 24K bytes). There 15 a reconciliation 
necessary in this case between the two dissimilar device 
types for the intermediate and output load module data sets; 
but the record size of the output load module data set 15 an 
even multiple of the record size of the intermediate data 
set so no adjustment of the record sizes 15 made. 

Therefore, the practical minimum, as well as the practical 
maximum and optimal value2 in this case is 24K bytes. 


2. A load module of more than 50K bytes is to be relink~-edited; 
however, a maximum of 40K bytes is available to be allocated 
to value2. The output load module data set 1s an old data 
set residing on a 3340, written with maximum record size. 
The intermediate data set is allocated to an IBM 2305-2 
Fixed Head Storage device. The link-edit involves a control 
section in the SYSLIN data set that will replace a control 
section in the old load module, followed by an INCLUDE 
statement naming the old load module on the SYSLMOD data 
set. The maximum for value2 cannot be satisfied, since only 
40K bytes is available. The size of two maximum records 
written to a 3340 would be 14K bytes. However, the size of 
one record to be written or to be read from the intermediate 
data set 1s 14K bytes. Therefore, the minimum for value2 in 
this case 1s 14K bytes. This is sufficient space for one 
input load module text record or one record written to or to 
be read from the intermediate data set or two records 
written to the output load module data set. 


3. The output load module data set resides on a 2305-2. The 


intermediate data set is allocated to a 3330. All load 
module input comes from a 3330. Value2 in this case is 24K 
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bytes, because the input load module text records are, at 
most, 12K bytes, the records written to and read from the 
intermediate data set are 12K bytes, and the records written 
to the output load module data set are 12K bytes. The 
maximum record size of 14K bytes for the 2305-2 is reduced 
to 12K bytes for this link-edit in order to be compatible 
with the intermediate data set. 


An alternative for value2 in the above example is 12K bytes. 
This 12K bytes is adequate for the input load module text 
records and the records written to and read from the 
intermediate data set. The 12K value forces a maximum 
record size of 6K bytes to be written to the output load 
module data set. At 6K bytes each, two records can be 
written on a 2305-2 track while, as in the above example, 
only one record of 12K bytes can be written on a 2305-2 
track. 


4. The output load module data set is a new data set allocated 
to a 3330. The programmer has specified the linkage editor 
parameter DCBS, and the SYSLMOD DD statement contains 
'...DCB=C€...BLKSIZE=3072,...),...". The only load module 
input comes from a data set created previously ina similar 
manner. The intermediate data set is allocated to a 3340. 
The minimum for value2 in this case is 6K bytes; the input 
load module records are 3K bytes at most, the intermediate 
data set records are 7K bytes at most, and, as directed by 
the programmer, the linkage editor produces records having a 
maximum size of 3K bytes on the output load module data set. 


VALUE]: Valuel specifies the number of bytes of virtual storage 
available to the linkage editor regardless of the private area 
size. The storage specified by valuel includes the allocation 
specified by value2. 


The absolute minimum for valuel is the design point of the 
linkage editor, 96K bytes. If a value less than the minimum for 


valuel is specified, the default options for both valuel and 
value2 are used. 


The practical minimum for valuel is 98304 (96K) bytes plus any 
excess in value2 over 6144 (6K) bytes, plus any additional space 
required to support the blocking factor for the SYSLIN, object 
module library, and SYSPRINT data sets. 


The design point of the linkage editor provides for the minimum 
load module buffer—6144¢ (6K) bytes of virtual storage. Ifa 
load module buffer larger than 6144 (6K) bytes is specified in 


value2, valuel must be increased by the excess of that value2 


over 6144 (6K) bytes. 


The linkage editor supports three different blocking factors for 
the SYSLIN, object module library, and SYSPRINT data sets; they 
are 5, 10, and 40 to 1. The requirement for additional space 
depends upon the blocking factor that is to be supported. 


The following table shows the additional space required to 
support each blocking factor. 


Blocking Space 
Factor Required 


10 to 1 18432 or 18K 
40 to l 28672 or 28K 


Blocking factors of 1 through 4, 6 through 9, and 11 through 39 
are treated as blocking factors of 5, 10, and 40, respectively. 
Blocking factors greater than 40 are invalid. 
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The additional space requirement is determined by the largest 
blocking factor among the affected data sets. 


The blocking factor supported is dependent upon Space available 
after value2 has been allocated to the load module buffer out of 


valuel. Therefore, if the space provided in valuel is 


insufficient, the next smallest blocking factor is used. 


The performance of the linkage editor can be improved by the 
allocation of additional storage by valuel, especially in 
providing for the optimal value2. 


The maximum value that can be specified for valuel is 9999999 or 
9999K. However, the amount of virtual storage actually 
allocated for valuel is the smaller of: 


® The region size 
® The amount specified for valuel 
Examples of Valuel Determination 


1. Assume that an optimum value2 of 36K bytes has already been 
determined for the link-edit. An appropriate valuel is 126K 
bytes, because an additional 30K bytes, above the minimum of 
96K bytes, 1s needed to support the allocation of 36K bytes 
to value2 and no additional storage is required to support 
the blocking factors for SYSLIN, SYSPRINT, and any object 
module libraries. 


2. The minimum for value2 (6K bytes) is used. All the object 
module libraries are blocked 5-to-1, except one that is 
blocked 10-to-1. The SYSLIN and SYSPRINT data sets are 
assigned blocking factors of 5. An appropriate valuel for 
this link-edit is 114K bytes, the minimum plus the 18K bytes 
needed to support the blocking factor of 10-to-1 on the 
object module library. 


The DCBS option allows the programmer to specify the block size 
for the SYSLMOD data set in the DCB parameter of SYSLMOD DD 
statement. 


If the DCBS option is specified, the block size value in the 
DSCB for the SYSLMOD data set may be overridden. If the DCBS 
option 1s not specified, the block size value in the DSCB for 
the SYSLMOD data set may not be overridden. 


If the DCBS option is specified and no block size value 15s 
provided in the DCB parameter of the SYSLMOD DD statement, the 
linkage editor uses the maximum track size for the device. If 
the DCBS option 1s not specified and a block size value 15s 
provided in the DCB parameter of the SYSLMOD DD statement, the 
block size value in the DCB parameter of the SYSLMOD DD 
statement is ignored by the linkage editor. 


Even though the DCBS option is specified, the linkage editor 
Will not allow the programmer to set the block size for the 
SYSLMOD data set to a value less than the minimum; that is, 256, 
or 1024 if the SCTR option is specified, or a value less than 
the block size in the DSCB for an existing data set. 


The block size specified by the programmer will be used unless 
(1) it is larger than the maximum record size for the device, in 
which case the maximum record size is used, or (2) it is less 
than the minimum block size, in which case the minimum block 
size is used. 


The following example shows the use of the DCBS option for an 
IBM 3350 Direct Access Storage device: 
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OUTPUT OPTIONS 


7/7LKED EXEC PGM=HEWL,PARM="XREF,DCBS' 


//7SYSLMOD DD DSNAME=LOADMODCTEST),DISP=C(NEW,KEEP), 
/7/ DCB=(BLKSIZE=3072),... 





As a result, the linkage editor uses a 3K-byte block size for 
the output module library. 


These options control the optional diagnostic output produced by 
the linkage editor. The programmer can request that the linkage 
editor produce a list of all control statements and a module map 
or cross-reference table to help in testing a program. The 
format of each 1s described in "Output from the Linkage Editor" 
on page 33. 


In addition, the programmer can request that the numbered 
error/warning messages generated by the linkage editor appear on 
the SYSTERM data set as well as on the SYSPRINT data set. 


Control Statement Listing Option 


Module Map Option 


To request a control statement listing, code LIST in the PARM 
field, as follows: 


//LKED EXEC PGM=-HEWL,PARM="LIST,...° 
When the LIST option is specified, all control statements 


processed by the linkage editor are listed in card-image format 
on the diagnostic output data set. 


To request a module map, code MAP in the PARM field, as follows: 
//LKED EXEC PGM=HEWL,PARM="MAP,...° 
When the MAP option is specified, the linkage editor produces a 


module map of the output module on the diagnostic output data 
set. 


Cross Reference Table Option 


To request a cross-reference table, code XREF in the PARM field, 
as follows: 


//LKED EXEC PGM=HEWL,PARM="XREF,...' 


When the XREF option is specified, the linkage editor produces a 
cross-reference table of the output module on the diagnostic 
output data set. The cross-reference table includes a module 
map; therefore, both XREF and MAP need not be specified for one 
linkage editor job step. 


Alternate Output (SYSTERM) Option 


To request that the numbered linkage editor error/warning 
messages be generated on the data set defined by a SYSTERM DD 
statement, code TERM in the PARM field, as follows: 


//LKED EXEC PGM=HEWL,PARM="TERM,...' 
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When the TERM option is specified, a SYSTERM DD statement must 
be provided. If it is not, the TERM option is negated. 


Output specified by the TERM option supplements printed 


diagnostic information; when TERM is used, linkage editor 
error/warning messages appear in both output data sets. 


INCOMPATIBLE JOB STEP OPTIONS 


When mutually exclusive job step options are specified for a 
linkage editor execution, the linkage editor ignores the less 


significant options. Figure 41 illustrates the significance of 
those options that are incompatible. When an X appears at an 
intersection, the options are incompatible. The option that 


appears higher in the list is selected. 
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Figure 41. Incompatible Job Step Options for the Linkage Editor 


For example, to check the compatibility of XREF and NE, follow 
the XREF column down and the NE row across until they intersect. 
Because an X appears where they intersect, they are 
Incompatible; XREF is selected; NE is negated. 
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If incorrect values are specified for the SIZE parameter, the 
default values are used. If incompatible options are detected, 
the message 


*¥¥* OPTIONS INCOMPATIBLE xx 


1s printed. This message follows the standard module 
disposition message. 


If the incompatible options OVLY and AMODE or RMODE are 
specified, a diagnostic message is issued. 


EXEC STATEMENT-—-REGION PARAMETER 


The REGION parameter specifies the maximum amount of storage 
that can be allocated to satisfy a request for storage that the 
linkage editor makes. In its minimal situation, the linkage 
editor requires a REGION parameter of not less than 96K bytes; 
in its default situation, not less than 256K bytes; and, in its 
maximal situation (see "Appendix D. Size Parameter Guidelines" 
on page 159), not less than 1500K bytes. 


EXEC STATEMENT~~RETURN CODE 
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The linkage editor passes a return code to the control program 
upon completion of the job step. The return code reflects the 
highest severity code recorded in any iteration of the linkage 
editor within that job step. The highest severity code 
encountered during processing is multiplied by 4 to create the 
return code; this code is placed into register 15 at the end of 
linkage editor processing. Figure 42 contains the return codes, 
the corresponding severity code, and a description of each. 


Return Severity 


Code Code Description 

00 0 Normal conclusion 

04 1 Warning messages have been listed; execution 
should be successful. For example, if the 


overlay option is specified and the overlay 
structure contains only one segment, a 
return code of 04 is placed in register 15. 


08 2 Error messages have been listed; execution 
may fail. The module is marked not executable 
unless the LET option is specified. For 
example, if the block size of a specified 
library data set cannot be handled by the 
linkage editor, a return code of 08 is placed 
in register 15. 


he 3 Severe errors have occurred; execution 15 
impossible. For example, if an invalid entry 
point has been specified, a return code of 0C 
1s placed in register 15. 


10 4 Terminal errors have occurred; the 
processing has terminated. For example, if 
the linkage editor cannot handle the blocking 
factor requested for SYSPRINT, a return code 
of 10 is placed in register 15. 


Figure 42. Linkage Editor Return Codes 


The programmer may use a return code to determine whether or not 
the load module is to be executed by using the condition 
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DD STATEMENTS 


parameter (COND) on the EXEC statement for the load module. The 
control program compares the return code with the values 
specified in the COND parameter, and the results of the 
comparisons are used to determine subsequent action. The COND 
parameter may be specified either in the JOB statement or the 
EXEC statement (see the publication JCL). 


Every data set used by the linkage editor must be described with 
a DD statement. Each DD statement must have a name, unless data 
sets are concatenated. The DD statements for data sets required 
by the linkage editor have preassigned names; those for 
additional input data sets have user-assigned names; those for 
concatenated data sets (after the first) have no names. 


In addition to the name, the DD statement provides the control 
program With information about the input/output device on which 
the data set resides, anda description of the data set itself. 
All of the job control language facilities for device 
description are available to the users of the linkage editor. 


Besides information about the device, the DD statement also 
contains a data set description which includes the data set name 
and its disposition. Information for the data control block 
(DCB) may also be given. 


General information pertinent to the linkage editor on the data 
set name and DCB information follows; information on disposition 
16 given in the discussion for each data set. 


DATA SET NAME: The linkage editor uses either sequential or 
partitioned data sets. For sequential data sets, only the name 
of the data set is specified; for partitioned data sets, the 
member name must also be specified either on the DD statement or 
with a control statement. 


When tnput data sets are passed from a previous job step, or 
when the output load module is being tested, a recommended 
practice is to use temporary data set names (that is, &&dsname). 
Use of temporary names ensures that there are no duplicate data 
sets with out-of-date modules. A data set with a temporary name 
is automatically deleted at the end of the job. When a module 
is to a stored permanently, a data set name without ampersands 
is used. 


DCB INFORMATION: Before a data set can be used for input, 
information describing the data set must be placed in the data 
control block (DCB). If this information does not exist in the 
DCB or header label, or if no labels are used (magnetic tape 
does not require labels), the programmer must specify it in the 
DCB parameter on the DD statement. 


Record format CRECFM), logical record size (LRECL), and block 
size (BLKSIZE) subparameters of the DCB parameter are discussed 
as they apply to the linkage editor. Specific information on 
each as it applies to the linkage editor data sets is given in 
the description of the data set later in this section. Other 
DCB information Ctape recording technique, density, and so 
forth) is described in the publication JCL. 


Record Format: The following record formats are used with the 
linkage editor: 


F The records are fixed length. 
FB The records are fixed length and blocked. 
FBA The records are fixed length, blocked, and contain 


American National Standard Institute CANSI) control 
characters. 
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FBS The records are fixed length, blocked, and written in 
standard blocks. 


FA The records are fixed length and contain ANSI control 
characters. 

FS The records are fixed length and written in standard 
blocks. 

U The records are undefined length. 

UA The records are undefined length and contain ANSI 


control characters. 


A record format of FS or FBS must be used with caution. All 
blocks in the data set must be the same size. This size must be 
equal to the specified block size. A truncated block can occur 
only as the last block in the data set. 


Note: Track overflow is never used by the linkage editor. When 
moving or copying load modules, it 15 recommended that the track 
overflow feature not be used on the target data set, as errors 
may occur in fetching the load modules for execution. 


LOGICAL RECORD AND BLOCK SIZE: Blocking is allowed for input 
object module data sets and the diagnostic output data set. The 
blocking factors used to determine buffer allocations are 5, 10, 
and 40. The BLKSIZE must therefore be a multiple of LRECL. See 
the description of blocking factors in the discussion of the 
SIZE option. 


When the DCBS option is specified, a block size should be 
specified for the output load module library (see "SYSLMOD DD 
Statement" on page 104). 


LINKAGE EDITOR DD STATEMENTS 


The linkage editor uses six data sets; of these, four are 
required. The DD statements for these data sets must use the 
preassigned ddnames given in Figure 43. The descriptions that 
follow give pertinent device and data set information for each 
linkage editor data set. 


Primary tnput data set SYSLIN 


Automatic call library SYSLIB Only if the 
automatic library 
call mechanism is 
used 


Intermediate data set SYSUT1 
Diagnostic output data set SYSPRINT 
Output module library SYSLMOD 


Alternate output data set SYSTERM Only if the TERM 
option is specified 


Figure 43. Linkage Editor ddnames 





SYSLIN DD Statement 
The SYSLIN DD statement is always required; it describes the 


primary input data set that can be assigned to a direct access 
device, a magnetic tape unit, or the card reader. The data set 
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SYSLIB DD Statement 


SYSUT1 DD Statement 


may be either sequential or partitioned; in the latter case, a 
member name must be specified. 


If SYSLIN is assigned to a card reader or “pseudo card reader,*™ 
input records must be unblocked and 80 bytes long. (A pseudo 
card reader is defined as input from a tape or a direct access 
device in card reader mode.) 


This data set must contain object modules and/or control 
statements. Load modules used in the primary input data set are 
considered a severity 4% error. 


The recommended disposition for the primary input data set 15 
SHR or OLD. 


The DCB requirements are shown in Figure 44. 


DCB Requirements 


LRECL BLKSIZE RECFM 
80 80 F,FS 
8&0 400,800,3200!? FB,FBS 


These are the maximum block sizes allowed for each of the 
optimal blocking factors (5, 10, and 40). Which maximum 1s 
applicable depends on the value given to valuel and valued of 
the SIZE option. 


Figure 44. DCB Requirements for Object Module and Control 
Statement Input 


The SYSLIB DD statement is required when the automatic 


library-call mechanism is to be used. This DD statement 
describes the automatic call library, which must be assigned to 
a direct access device. The data set must be partitioned, but 


member names should not be specified. 
The recommended disposition for the call library is SHR or OLD. 


If concatenated call libraries are used, object and load module 
libraries must not be mixed. If only object modules are used, 
the call library may also contain control statements. 


The DCB requirements for object module call libraries are given 
in Figure 44. The DCB requirement for load module call 
libraries is a record format of U; the block size used for 
storage allocation 15S equal to the maximum for the device used, 
not the record read. Note that the linkage editor recognizes 
object and load module call libraries solely from their record 
format, and not from the data within them. 


This data set must not be assigned to SYSOUT. 


The SYSUT1 DD statement is always required; it describes the 
intermediate data set, which is a sequential data set assigned 
to a direct access device. Space must be allocated for this 
oe set, but the DCB requirements are supplied by the linkage 
editor. 
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SYSPRINT DD Statement 


SYSLMOD DD Statement 
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The SYSPRINT DD statement is always required; it describes the 
diagnostic output data set, which is a sequential data set 
assigned to a printer or to an intermediate storage device. If 
an intermediate storage device is used, the data records contain 
a carriage control character as the first byte. 


The usual specification for this data set is SYSOUT=A. The 
programmer may assign a block size. The record format assigned 
ss ahs linkage editor depends on whether blocking is used or 
not. 


Figure 45 shows the DCB requirements for SYSPRINT. The only 


information that can be supplied by the programmer is the block 
size. 


DCB Requirements for SYSPRINT 


LRECL BLKSIZE RECFM 
121 121 FA 
121 n x 121 where n FBA 


1s less than or 
equal to 40 


Note: The value specified for BLKSIZE, either on the DCB 
parameter of the SYSPRINT DD statement or in the DSCB (data set 
control block) of an existing data set, must be a multiple of 
121; if it is not, the linkage editor issues a message to the 
operator's console and terminates processing. 


Figure 45. DCB Requirements for SYSPRINT 


The SYSLMOD DD statement is always required; it describes the 
output module library, which must be a partitioned data set 
assigned to a direct access device. 


A member name may be specified on the SYSLMOD DD statement. If 
a member name is specified, it 1s used only if a name was not 
specified on a NAME control statement. This member name must 
conform to the rules for the name on the NAME control statement. 
This would imply the replacement of an identically named member 
in the output load module library, if one exists. 


If SYSLMOD is to be referenced by an INCLUDE statement, the 
member name on the DD statement, if present, must be the name of 
an existing member. 


If the member is to replace an identically named member in an 
existing library, the disposition should be OLD or SHR. If the 
member is to be added to an existing library, the disposition 
should be MOD, OLD, or SHR. If no library exists and the member 
is the first to be added to a new library, the disposition 
should be NEW or MOD. If the member is to be added to an 
existing library that may be used concurrently in another region 
or partition, the disposition should be SHR. 


The record format U is assigned by the linkage editor. See 
"Appendix G. Storage Considerations™ on page 180. 


Procedures used by the linkage editor to assign block size are: 
1 If the data set 1s new: 
a. Without the DCBS option speci fied: 
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e The DSCB (data set control block) reflects the 

maximum block size available for the device type if 
it is not restricted by value2 of the size 
parameter. 


e If SCTR is specified, the block size is 1024. 


b. With the DCBS option specified, the DSCB block size is 
the smaller of: 


° The maximum track size for the device. 


° The value of the BLKSIZE subparameter on the DCB 
parameter of the SYSLMOD DD statement. 


° The actual output buffer length Chalf the number 
specified for value2 if the size option was 
utilized). 


c. The minimum DSCB block size is 256 without the SCTR 
option specified and 1024 with the SCTR option. 


2. For preallocated data sets not previously opened, a block 
size is assigned as for new data sets. 


3. When the DSCB block size already exists (not a new or 
preallocated data set) and the SCTR option is specified, 
1024 is used. 


4. When the DSCB block size already exists and the DCBS or SCTR 
option is not specified, the larger of the existing block 
sizes or 256 is used. 


5. See "DCBS Option" on page 97 for the procedure when the DSCB 
block size exists and the DCBS option is specified. 


c Note: When a new data set is created at linkage editor time 
without the DCBS option specified, the DSCB reflects the maximum 
block size available for the device type. 


If the SYSLMOD DD statement is used as a source of load module 
oe the SYSLMOD data set is read with a record format of U in 
all cases. 


In the following example, the SYSLMOD DD statement specifies a 
permanent library on an IBM 3350 Disk Storage Device: 


//SYSLMOD DD DSNAME=USERLIBCTAXES),DISP=MOD, 
4/ UNIF=3350,... 


The linkage editor assigns a record format of U, and a logical 
record and block size of 18K bytes, the maximum for a 3350. 
However, consider the following example: 


//LKED EXEC PGM=HEWL,PARM="XREF,DCBS' 


//SYSLMOD DD DSNAME=-USERLIBCTAXES),DISP=MOD, 
// UNIT=3340,DCB=(BLKSIZE=3072),. 





The linkage editor still assigns a record format of U, but the 
logical record and block size are now 3K bytes rather than 7K 
bytes, because of the use of the DCBS option. 


Cc SYSTERM DD Statement 


The SYSTERM DD statement is optional; it describes a data set 
that is used only for numbered error/warning messages. Although 
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intended to define the terminal data set when the linkage editor 
is being used under the Time Sharing Option (TSO) of MVS, the 
SYSTERM DD statement can be used in any environment to define a 
data set consisting of numbered error/warning messages that 
supplements the SYSPRINT data set. 


SYSTERM output is defined by including a SYSTERM DD statement 
and specifying TERM in the PARM field of the EXEC statement. 
When SYSTERM output is defined, numbered messages are then 
written to both the SYSTERM and SYSPRINT data sets. 


The following example shows how the SYSTERM DD statement could 
be used to specify the system output unit: 


4/SYSTERM DD SYSOUT=A 


The DCB requirements for SYSTERM (CLRECL=121,BLKSIZE=121, and 
RECFM=FBA) are supplied by the linkage editor. If necessary, 
the linkage editor will modify the DSCB (data set control block) 
of an existing data set to reflect these values. 


ADDITIONAL DD STATEMENTS 
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Each ddname specified on an INCLUDE or a LIBRARY control 
statement must also be described with a DD statement. These DD 
statements describe sequential or partitioned data sets, 
assigned to magnetic tape units or direct access devices (not 
pseudo card readers). 


The ddnames are specified by the user with any other necessary 
information. The DCB requirements for these data sets are shown 
in Figure 46. 


LRECL BLKSIZE RECFM 


Include Control Statement 


Object modules and/or 80 80 F,FS 
control statements 


Load modules maximum equal to U 
for device, LRECL 
or one-half 
of valued, 
whichever 
is smaller 


Library Control Statement 


Object modules and/or 80 80 F,FS 
control statements 80 400,800,3200! FB,FBS 
Load Modules maximum equal to U 


for device, LRECL 
or one-half 

of value2, 
whichever 

is smaller 


Figure 46. DCB Requirements for Additional Input Data Sets 





Note to Figure 46: 


1 These are the maximum block sizes allowed for each of the 
optimal blocking factors (5, 10, 40). Which maximum is 
applicable depends on the values given to valuel and value2 
of the SIZE option. 
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When concatenated data sets are included, each data set must 
contain records of the same format, record size, and block size. 
If the data sets reside on magnetic tape, the tape recording 
technique and density must also be identical. 


If the SYSLMOD ND statement is used as a source of load module 
input, the SYSLMOD data set is read with a record format of U in 
all cases. 


CATALOGED PROCEDURES 


To facilitate the operation of the system, the control program 
allows the programmer to store EXEC and DD statements under a 
unique member name in a procedure library. Such a series of job 
control language statements is called a cataloged procedure. 
These job control language statements can be re-called at any 
time to specify the requirements for a job. To request this 
procedure, the programmer places an EXEC statement in the input 
stream. This EXEC statement specifies the unique member name of 
the procedure desired. 


The specifications in a cataloged procedure can be temporarily 
overridden, and DD statements can be added. The information 
altered by the programmer is in effect only for the duration of 
the job step; the cataloged procedures themselves are not 
altered permanently. Any additional DD statements supplied by 
the programmer must follow those that override the cataloged 
procedure. 


LINKAGE EDITOR CATALOGED PROCEDURES 


Procedure LKED 


Two linkage editor cataloged procedures are provided: a 
single-step procedure that link-edits the input and produces a 
load module (procedure LKED), and a two-step procedure that 
link-edits the input, produces a load module, and executes that 
module (procedure LKEDG). Many of the cataloged procedures 
provided for language translators also contain linkage editor 
steps. The EXEC and DD statement specifications in these steps 
are similar to the specifications in the cataloged procedures 
described in the following paragraphs. 


The cataloged procedure named LKED is a single-step procedure 
that link-edits the input, produces a load module, and passes 
the load module to another step in the same job. The statements 
in this procedure are shown in Figure 47; the following text 
describes these statements. 


//LKED EXEC PGM=HEWL,PARM='XREF,LIST,LET,NCAL',REGION=96K 
//SYSPRINT DD SYSOUT=A 

//SYSLIN DD DDNAME=SYSIN 

//SYSLMOD DD DSNAME=&&GOSET(GO),SPACE=(1024,(050,20,1)), 

17 UNIT=SYSDA,DISP=(MOD,PASS) 

//SYSUTI DD UNIT=CSYSDA,SEP=(SYSLMOD,SYSLIN)), 

7 SPACE=(1024,(200,20)) 


Figure 47. Statements in the LKED Cataloged Procedure 


STATEMENT NUMBERS: The 8&-digit numbers on the right side of each 
statement (not shown in Figure 47) are used to identify each 
statement and would be used, for example, when permanently 
modifying the cataloged procedure with the system utility 
program IEBUPDTE. For a description of this utility program, 
see Utilities. 
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and NCAL options. If the automatic library-call mechanism is to 
be used, the NCAL option must be overridden, and a SYSLIB DD 
statement must be added. Overriding and adding DD statements is 
discussed later in this section. 


EXEC STATEMENT: The PARM field specifies the XREF, LIST, LET, : 


SYSPRINT STATEMENT: The SYSPRINT DD statement specifies the 
SYSOUT class A, which 1s either a printer or an intermediate 
storage device. If an intermediate storage device is used, 
American National Standard Institute control characters 
accompany the data to be printed. 


SYSLIN STATEMENT: The specification of DDNAME=SYSIN allows the 
programmer to specify any input data set as long as it fulfills 
the requirements for linkage editor input. The input data set 
must be defined with a DD statement with the ddname SYSIN. This 
data set may be either in the input stream or reside ona 
separate volume. 


If the data set is in the input stream, the following SYSIN 
statement is used: 


//LKED.SYSIN DD x 


If this SYSIN statement is used, it may be anywhere in the job 
step DD statements as long as it follows all overriding DD 
statements. The object module decks and/or control statements 
should follow the SYSIN statement, with a delimiter statement 
(7%) at the end of the input. 


If the data set resides on a separate volume, the following 
SYSIN statement is used: 


//LKED.SYSIN DD (parameters describing the input data set) 


If this SYSIN statement is used, it may be anywhere in the job 

step DD statements as long as it follows all overriding DD veg” 
statements. Several data sets may be concatenated, as described 

in "Input to the Linkage Editor™ on page 19. 


SYSLMOD STATEMENT: The SYSLMOD DD statement specifies a 
temporary data set and a general space allocation. The 
disposition allows the next job step to execute the load module. 
If the load module is to reside permanently ina library, these 
general specifications must be overridden. 


SYSUTL STATEMENT: The SYSUT1 DD statement specifies that the 
intermediate data set is to reside ona direct access device, 
but not the same device as either the SYSLMOD or the SYSLIN data 
sets. Again, a general space allocation is given. 


SYSLIB STATEMENT: Note that there is no SYSLIB DD statement. If 
the automatic library-call mechanism is to be used with a 
cataloged procedure, a SYSLIB DD statement must be added; also, 
the ae option in the PARM field of the EXEC statement must be 
negated. 


INVOKING THE LKED PROCEDURE: To invoke the LKED procedure, code 
the following EXEC statement: 


//stepname EXEC LKED 

where stepname is optional and is the name of the job step. 

The following example shows a sample JCL sequence for using the 
LKED procedure in one step to link-edit object modules to 


produce a load module, then execute the load module in a 
subsequent step. 
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Procedure LKEDG 


//LESTEP EXEC LKED 

(Overriding and additional DD statements for the LKED step) 
//LKED.SYSIN DD x 

(Object module decks and/or control statements) 
//7EXSTEP EXEC PGM=*% .LESTEP.LKED.SYSLMOD 


(DD statements and data for load module execution) 


/# CIf data is supplied for the execution step) 





Note: LESTEP invokes the LKED procedure and EXSTEP executes the 
load module produced by LESTEP. 


The cataloged procedure named LKEDG is a two-step procedure that 
link-edits the input, produces a load module, and executes that 
load module. The statements in this procedure are shown in 
Figure 48. The two steps are named LKED and GO. The 
specifications in the statements in the LKED step are identical 
to the specifications in the LKED procedure. 


//LKED EXEC PGM=HEWL,PARM="XREF,LIST,NCAL*,REGION=96K 
//SYSPRINT DD SYSOUT=A 

“/SYSLIN DD DDNAME=SYSIN 

//SYSLMOD DD DSNAME=&&GOSET(GO), SPACE=(1024,(50,20,1)), 
17 UNIT=CSYSDA,DISP=C(MOD,PASS) 

//SYSUTI DD UNIT=(SYSDA,SEP=(SYSLMOD,SYSLIN)), 

// SPACE=(1024,(200,20)) 

//G0 EXEC PGM=* .LKED.SYSLMOD, COND=(4,LT,LKED) 


Figure 48. Statements in the LKEDG Cataloged Procedure 


GO STEP: The EXEC statement specifies that the program to be 
executed 1s the load module produced in the LKED step of this 
job. This module was stored in the data set described on the 
SYSLMOD DD statement in that step. CIf a NAME statement was 
used to specify a member name other than that used on the 
SYSLMOD statement, use the LKED procedure. ) 


The condition parameter specifies that the execution step is to 
be bypassed if the return code issued by the LKED step is 
greater than 4. 


INVOKING THE LKEDG PROCEDURE: To invoke the LKEDG procedure, 
code the following EXEC statement: 


//stepname EXEC LKEDG 
where stepname is optional and is the name of the job step. 
The following example shows a sample JCL sequence for using the 


LKEDG procedure to link-edit object modules, produce a load 
module, and execute that load module. 
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//TWOSTEP EXEC LKEDG. 


COverriding and additional DD statements for the LKED step) 


//LKED.SYSIN DD % 

(Object module decks and/or control statements) 
7% 

(DD statements for the GO step) 
//GO.SYSIN DD % 

(Data for the GO step) 


7% 





OVERRIDING CATALOGED PROCEDURES 


Overriding the EXEC 


The programmer may override any of the EXEC or DD statement 
specifications in a cataloged procedure. These new 
specifications remain in effect only for the duration of the job 
step. For a detailed description of overriding cataloged 
procedures, see the publication JCL. 


Statement 


The EXEC statement in a cataloged procedure is overridden by 
specifying the changes and additions on the EXEC statement that 
invokes the cataloged procedure. The stepname should be 
specified when overriding the EXEC statement parameters. 


For example, the REGION parameter can be increased as follows: 
//LESTEP EXEC LKED,REGION.LKED=136K 


The rest of the specifications on the EXEC statement of 
procedure LKED remain in effect. 


If the PARM field is to be overridden, all the options specified 
in the cataloged procedure are negated. That 1s, if XREF, LIST, 
or NCAL is desired when overriding the PARM field, it must be 
respecified. In the following example, the OVLY option is added 
and the NCAL option is negated: 


/7/LESTEP EXEC LKED,PARM.LKED="OVLY,XREF,LIST* 


As a result, the XREF and LIST options are retained, but the 
NCAL option is negated; when NCAL 1s negated, a SYSLIB DD 
statement must be added. 


If you use the LKEDG procedure and want to execute the load 
module just built, an efficient way is to specify the parameter 
LET in the LKED step and invoke the LKEDG procedure with the 
following EXEC statement: 


//stepname EXEC LKEDG,PARM.LKED="*XREF,LIST,NCAL,LET', 


7 COND.GO=(8,LT,LKED) 
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ADDING DD STATEMENTS 


Overriding DD Statements 


Each DD statement that is used to override a DD statement in the 
LKED step of either the LKED procedure or the LKEDG procedure 
must begin with //LKED.ddname... . 


Any of the DD statements in the cataloged procedures can be 
overridden as long as the overriding DD statements are in the 
same order as they appear in the procedure. If any DD 
statements are not overridden, or overriding DD statements are 
included but are not in sequence, the specifications in the 
cataloged procedure are used. 


Only those parameters specified on the overriding DD statement 
are affected; the rest of the parameters remain as specified in 
the procedure. In the following example, the output load module 
is to be placed in a permanent library: 


//LIBUPDTE EXEC LKED 


7/LKED.SYSLMOD DD DSNAME=LOADLIBCPAYROLL),DISP=OLD 
//LKED.SYSIN DD DSNAME=OBJMOD, DISP=(OLD, DELETE) 





Unit and volume information should be given if these data sets 
are not cataloged. 


As a result of the statements in the example, the LKED procedure 
is used to process the object module in the OBJMOD data set. 

The output load module is stored in the data set LOADLIB with 
the name PAYROLL. The SPACE parameter on the SYSLMOD DD 

Spahr Will and the other specifications in the procedure remain 
in effect. 


DD statements for additional data sets can be supplied when 
using cataloged procedures. These additional DD statements must 
follow any overriding DD statements. 


Each additional DD statement for the LKED step must begin with 
//LKED.ddname... and, for the GO step, must begin with 
//GO0.ddname... 


In the following example, the automatic library-call mechanism 
1s to be used along with the LKEDG procedure: 


//CPSTEP EXEC LKEDG,PARM.LKED='XREF,LIST’ 
//LKED.SYSLMOD DD DSNAME=LOADLIBCTESTER),DISP=OLD,... 
7/LKED.SYSLIB DD DSNAME=SYL1.PL1LIB,DISP=SHR 
//LKED.SYSIN DD % 


CObjyect module decks and/or control statements). 


7% 
4/GO.SYSIN DD % 


(Data for execution step) 


7% 





The NCAL option is negated, and a SYSLIB DD statement is added 
shaarpatelt ia overriding SYSLMOD DD statement and the SYSIN DD 
statement. 
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LINKAGE EDITOR CONTROL STATEMENT SUMMARY 


General Format 


Format Conventions 


This chapter summarizes the linkage editor control statements. 
The description of each statement includes: 


e What the statement does 
e The format of the statement 


e Placement of the statement in the input 
e Notes on use, if any 
e One or more examples that include job control language 


statements, when necessary 


The control statements are described in alphabetic order. 

Before using this chapter, the user should be familiar with the 
following information on general format, format conventions, and 
placement. 


Each linkage editor control statement specifies an operation and 
one or more operands. Nothing must be written preceding the 
operation, which must begin in or after columm 2. The operation 
must be separated from the operand by one or more blanks. 


A control statement can be continued on as many cards as 
necessary by terminating the operand at a comma, and by placing 
a nonblank character in column 72 of the card. Continuation 
must begin in column 16 of the next card. A symbol cannot be 
split; that is, it cannot begin on one card and be continued on 
the next. 


The following conventions are used in the formats to describe 
the coding of the linkage editor control statements: 


e Boldface type indicates the exact characters to be entered. 
Such items must be entered exactly as illustrated (Cin 
uppercase, if applicable). 


° Lowercase underscored type specifies fields to be supplied 
by the user. 


e Other punctuation (parentheses, commas, spaces, etc.) must 
be entered as shown. 


e Braces { } indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 


e Brackets [ ] indicate an optional field or parameter. 


° An ellipsis (...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. 


° Items separated by a vertical bar ( | ) represent 
alternative items. No more than one of the items may be 
selected. 


Placement Information 


Linkage editor control statements are placed before, between, or 
after modules. They can be grouped, but they cannot be placed 
Within a module. However, specific placement restrictions may 
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be imposed by the nature of the functions being requested by the 
control statement. Any placement restrictions are noted. 
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ALIAS Statement 





The ALIAS statement specifies additional names for the output ) 
library member, and can also specify names of alternative entry 

points. Up to 16 names can be specified on one ALIAS statement, 

or separate ALIAS statements for one library member. The names 

are entered in the directory of the partitioned data set in 

addition to the member name. 


FORMAT: The format of the ALIAS statement is: 


ALIAS {symbollexternal name} 


symbol 
specifies an alternate name for the load module. When the 


module 1s executed, the main entry point is used as the 
starting point for execution. 


external name 


specifies a name that is defined as a control section name 
or entry name in the output module. When the module is 
called for execution, execution begins at the external name 
referred to. 


PLACEMENT: An ALIAS statement can be placed before, between, or 
after object modules or other control statements. It must 
precede a NAME statement used to specify the member name, if one 
1s present. 


Notes: 


l. In an overlay program, an external name specified by the 
ALIAS statement must be in the root segment. 


2. No more than 16 aliasS names can be assigned to one output ; 
module. 


3. Each alias specified for a load module is retained in the 
directory entry for the module; the linkage editor does not 
delete an old alias. Therefore, each alias that is specified 
must be unique; assigning the same alias to more than one 
load module can cause incorrect module references. 


4. Obsolete alias names should be deleted from the PDS 
directory using a system utility such as IJEHPROGM, to avoid 
future name conflicts. 


5. If the replace option is in effect for the output load 
module (that is, the load module built in this link-edit 
does or may replace an identically named load module in the 
output module library), the replace option is in effect for 
each ALIAS name for the load module as well as for the 
primary name. 


EXAMPLE: An output module, ROUTI1, is to be assigned two 
alternate entry points, CODE1 and CODE2. In addition, calling 
modules have been written using both ROUT1 and ROUTONE to refer 
to the output module. Rather than correct the calling modules, 
an alternative library member name is also assigned. 


ALIAS CODE1,CODE2,ROUTONE 
NAME ROUT1 


Because CODE1 and CODE2 are entry names in the output module, 

execution begins at the point referred to when these names are 

used to call the module. The modules that call the output 

module with the name ROUTONE now correctly refer to ROUT1 at its 

main entry point. The names CODE1, CODE2, and ROUTONE appear in 

the library directory along with ROUTI. ) 
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CHANGE Statement 


The CHANGE statement causes an external symbol to be replaced by 
the symbol in parentheses following the external symbol. The 
external symbol to be changed can be a control section name, an 
entry name, or an external reference. More than one such 
substitution may be specified in one CHANGE statement. 


FORMAT: The format of the CHANGE statement is: 


external symbol (newsymbol ) 
[,externalsymbol (newsymbol J]... 


externalsymbol 
1s the control section name, entry name, or external 
reference that 15 to be changed. 


newsymbol 
is the name to which the external symbol is to be changed. 


PLACEMENT: The CHANGE control statement must be placed 
immediately before either the module containing the external 
symbol to be changed, or the INCLUDE control statement 
specifying the module. The scope of the CHANGE statement is 
across the immediately following module Cobjyect module or load 
module); the END record in the immediately following object 
module or the end-of-module indication in the immediately 
following load module delimits the scope of the CHANGE 
statement. 


Notes: 


1. External references from other modules to a changed control 
section name or entry name remain unresolved unless further 
action is taken. 


2. If the external symbol specified on the CHANGE statement is 
misspelled, the symbol will not be changed. Linkage editor 
output, such as the cross-reference listing or module map, 
can be used to verify each change. 


3. When a REPLACE statement that deletes a control section is 
followed by a CHANGE statement with the same control section 
name, unpredictable results will occur. 


EXAMPLE 1: Two control sections in different modules have the 
name TAXROUT. Because both modules are to be link-edited 
together, one of the control section names must be changed. The 
module to be changed is defined with a DD statement named 
OBJMOD. The control section name could be changed as follows: 


//O0BJMOD DD DSNAME=TAXES,DISP=COLD,KEEP),... 
//SYSLIN DD * 
CHANGE TAXROUTCSTATETAX) 


INCLUDE OBJMOD 


7¥ 





As a result, the name of control section TAXROUT in module TAXES 
15 changed to STATETAX. 
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EXAMPLE 2: A load module contains references to TAXROUT that 

must now be changed to STATETAX. This module is defined with a 

DD statement named LOADMOD. The external references could be 

rates at the same time the control section name is changed, as 
ollows: 


//OBJMOD DD DSNAME=TAXES,DISP=COLD,DELETE),... 
//LOADMOD DD DSNAME=LOADLIB,DISP=OLD,... 
/SYSLIN DD x 

CHANGE TAXROUTCSTATETAX) 

INCLUDE OBJMOD 


CHANGE TAXROUTCSTATETAX) 
INCLUDE LOADMODCINVENTRY) 


7% 





As a result, control section name TAXROUT in module TAXES and 
external reference TAXROUT in module INVENTRY are both changed 
to STATETAX. 
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ENTRY Statement 


The ENTRY statement specifies the symbolic name of the first 
instruction to be executed when the program is called by its 
module name for execution. An ENTRY statement should be used 
whenever a module is reprocessed by the linkage editor. If more 
than one ENTRY statement is encountered, the first statement 
seen the main entry point; all other ENTRY statements are 
ignored. 


FORMAT: The format of the ENTRY statement is: 


externalname 
is defined as either a control section name or an entry 
name ina linkage editor input module. 


PLACEMENT: An ENTRY statement can be placed before, between, or 
after object modules or other control statements. It must 
precede the NAME statement for the module, if one is present. 


Notes: 


1.3 In an overlay program, the first instruction to be executed 
must be in the root segment. 


2. The external name specified must be the name of an 
instruction, not a data name, if the module is to be 
executed. 


EXAMPLE: In the following example, the main entry point is 
INIT1: 


//LOADLIB DD DSNAME=LOADLIB,DISP=OLD,... 
7/SYSLIN DD % 

ENTRY INITI 

INCLUDE LOADLIBCREAD,WRITE) 


ENTRY READIN 
/* 





INIT1 must be either a control section name or an entry name in 
the linkage editor input. The entry point specification of 
READIN is ignored. 
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EXPAND Statement 


The EXPAND statement lengthens control sections or named common 2 
sections by a specified number of bytes. 


FORNAT: The format of an EXPAND statement is 


namel(xxxx ) 
L»namelxxxxJ]... 


name 
is the symbolic name of a common section or control section 
whose length is to be increased. 





1s the decimal number of bytes to be added to the length of 
a common section. The maximum is 4095 for each section 
indicated. Binary zeros will be added for an expanded 
control section. 


The EXPAND statement is followed by a message, IEW0740, that 
indicates the number of bytes added to the control section and 
the offset, relative to the start of the control section, at 
which the expansion begins. The effective length of the 
expansion 1s given in hexadecimal and may be greater than the 
specified length if, after the specified expansion, padding 
bytes must be added for alignment of the next control section or 
named common section. 


PLACEMENT: An EXPAND statement can be placed before, between, or 

after other control statements or object modules. However, the 
statement must follow the module containing the control or named 

common section to which it refers. If the control section or 

named common section is entered as the result of an INCLUDE 

statement, the EXPAND statement must immediately follow the ) 
INCLUDE statement. 


Note: EXPAND should be used with caution so as not to increase 

the length of a program beyond its own design limitations. For 

example, if space 1s added to a control section beyond the range 
of its base register addressability, that space 1s unusable. 


EXAMPLE: In the following example, EXPAND statements add a 
250-byte patch area Cinitialized to zeros) at the end of control 
section CSECT1 and increase the length of named common section 
COM1 by 400 bytes. 


//LKED PGM=HEWL 

7/SYSPRINT SYSOUT=A 

7/SYSUT1 UNIT=SYSDA,SPACE=CTRK, €10,4)) 
7/SYSLMOD DSNAME=PDSX, DISP=OLD 

//SYSLIN DSNAME=&&LOADSET, DISP=COLD,PASS), 


// UNIT=SYSDA 

47 ¥ 
EXPAND CSECT1¢250) 
EXPAND COM1(400) 
NAME MODICR) 

7 * 
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IDENTIFY Statement 
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i 
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t 


The IDENTIFY statement specifies any data supplied by th” user 
to be entered into the CSECT identification (IDR) records for a 
Particular control section. The statement can be used either to 
supply descriptive data for a control section or to provide a 
means of associating system-supplied data with executable code. 


FORMAT: The format of the IDENTIFY statement is: 


eect 


IDENTIFY csectnamel'data' JI,csectnamel("'data')J]... 





csectname 


is the symbolic name of the control section to be 
identified. 


data 





specifies up to 40 EBCDIC characters of identifying 
information. The user may supply any information desired 
for identification purposes. 


The rules of syntax for the operand field are: 


1. No blanks or characters may appear between the left 
parenthesis and the leading single quotation mark nor 
between the trailing single quotation mark and the right 
parenthesis. 


2. The data field consists of from 1 to 40 characters; 
: therefore, a null entry must be represented, minimally, by a 
single blank. 


3. Blanks may appear between the leading single quotation mark 
and the trailing single quotation mark. Each blank counts 
as 1 character toward the 40-character limit. 


4. <A single quotation mark between the leading quotation mark 
and the trailing quotation mark is represented by 2 
consecutive quotation marks. The pair of quotation marks 
counts as 1 character toward the 40-character limit. 


5. Any EBCDIC character may appear between the leading 


quotation mark and the trailing quotation mark. Each 
character counts as 1 character toward the 40-character 
limit. 


6. The IDENTIFY statement may be continued; however, a whole 
operand must appear ona single card image and at least 1 
whole operand must appear on each card image of the 
continued statement. 


Ls If a leading quotation mark is found, all characters are 
absorbed until a trailing quotation mark is found or the 
40-character limit is exhausted. 


8. Blanks may not appear between the CSECT name and the left 
parenthesis. 


9. A blank following a left parenthesis terminates the operand 
field; a blank following a comma that terminates an operand 
also terminates the operand field of that card image. 


PLACEMENT: An IDENTIFY statement can be placed before, between, 
or after other control statements or object modules. The 
IDENTIFY statement must follow the module containing the control 
ee to be identified or the INCLUDE statement specifying the 
module. 


Note: When two or more IDENTIFY statements specify the same 
CSECT name, only the last statement is effective. 
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EXAMPLE: In the following example, IDENTIFY statements are used 
to identify the source level of a control section, a PTF 
application to a control section, and the functions of several 
control sections. 


//LKED EXEC PGM=HEWL 

Z/SYSPRINT DD SYSOUT=A 

//SYSUTI DD UNIT=SYSDA,SPACE=CTRK,(10,5)) 
//SYSLMOD DD DSNAME=LOADSET,DISP=OLD 
//0OLDMOD DD DSNAME=-OLD.LOADSET,DISP=OLD 
//PTFMOD DD DSNAME=PTF.OBJECT,DISP=OLD 
//SYSLIN DD % 


Cinput object deck for a control section named FORT) 


IDENTIFY FORTC'LEVEL 03°) 

INCLUDE PTFMODCCSECT4) 

IDENTIFY CSECT4('PTF99999" ) 

INCLUDE OLDMODC(CPROG1) 

IDENTIFY CSECTIC'IZO ROUTINE'), 
CSECT2C'SORT ROUTINE'), 
CSECT3C'SCAN ROUTINE’) 





Execution of this example produces IDR records containing the 
following identification data: 


@ The name of the linkage editor that produced the load 
module, the linkage editor version and modification level, 
and the date of the current linkage editor processing of the 
module. This information is provided automatically. 


e User-supplied data describing the functions of several 
control sections in the module, as indicated on the third 
IDENTIFY statement. 


e If the language translator used supports IDR, the 
identification records produced by the linkage editor also 
contain the name of the translator that produced the object 
module, its version and modification level, and the data of 
compilation. 


The IDR records created by the linkage editor can be referenced 
by using the LISTIDR function of the service aid program 
AMBLIST. For instructions on how to use AMBLIST, see System 
Programming Library: Service Aids. 
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INCLUDE Statement 


The INCLUDE statement specifies sequential data sets and/or 
libraries that are to be sources of additional input for the 
linkage editor. INCLUDE statements are processed in the order 
in which they appear in the input. However, the sequence of 
data sets and modules within the output load module does not 
necessarily follow the order of the INCLUDE statements. 


FORMAT: The format of the INCLUDE statement is: 


INCLUDE 





ddname 


is the name of a DD statement that describes either a 
sequential or a partitioned data set to be used as 
additional input to the linkage editor. For a sequential 
data set, ddname is all that must be specified. For a 
partitioned data set, at least one member name must also be 
specified. 


membername 


1s the name of or an alias for a member of the library 
defined in the specified DD statement. The membername must 
not be specified again on the DD statement. 


PLACEMENT: An INCLUDE statement can be placed before, between, 
or after object modules or other control statements. 


Note: <A NAME statement in any data set specified in an INCLUDE 
statement is invalid; the NAME statement is ignored. All other 
control statements are processed. 


EXAMPLE 1: In the following example, an INCLUDE statement 
specifies two data sets to be the input to the linkage editor: 


//OBJMOD DD DSNAME=&& OBJECT, DISP=COLD,DELETE) 
//LOADMOD DD DSNAME=LOADLIB,DISP=SHR,... 


//SYSLIN DD x 
INCLUDE OBJMOD,_LOADMODCTESTMOD, READMOD) 
/* 





Note that a DD statement must be supplied for every ddname 
specified in an INCLUDE statement. 


EXAMPLE 2: Two separate INCLUDE statements could have been used 
in the preceding example, as follows: 


INCLUDE OBJMOD 
INCLUDE LOADMODCTESTMOD,READMOD) 
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INSERT Statement 








The INSERT statement repositions a control section from its J 
position in the input sequence to a segment in an overlay 
structure. However, the sequence of control sections within a 


segment is not necessarily the order of the INSERT statements. 


If a symbol specified in the operand field of an INSERT 
statement 1s not present in the external symbol dictionary, it 
1s entered as an external reference. If the reference has not 
been resolved at the end of primary input processing, the 
automatic library-call mechanism attempts to resolve it. 


FORMAT: The format of the INSERT statement is: 


csectname 


1s the name of the control section to be repositioned. A 
particular control section can appear only once within a 
load module. 


PLACEMENT: The INSERT statement must be placed in the input 
sequence following the OVERLAY statement that specifies the 
origin of the segment in which the control section is to be 
positioned. If the control section is to be positioned in the 
root segment, the INSERT statement must be placed before the 
first OVERLAY statement. 


Note: Control sections that are positioned in a segment must 
contain all address constants to be used during execution 
unless: 


° The A-type address constants are located in a segment in the ) 
path. 


° The V-type address constants used to pass control to another 
segment are located in the path. If an exclusive reference 
1s made, the V-type address constant must be in a common 
segment. 


e The V-type address constants used with the SEGLD and SEGWT 
macro instructions are located in the segment. 


EXAMPLE: The following INSERT Cand OVERLAY) statements speci fy 
the overlay structure shown in Figure 49 on page 123: 


EXEC PGM=HEWL,PARM="OVLY,XREF,LIST' 


//SYSLIN DD 
INSERT CSA 
INSERT CSB 
OVERLAY ALPHA 
INSERT CSC,CSD 
OVERLAY ALPHA 
INSERT CSE 

/¥ 
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LIBRARY Statement 


CSA 
CSB 
ALPHA 
CSC 
CSE 
CSD 


Figure 49. Overlay Structure for INSERT Statement Example 


The LIBRARY statement can be used to Specify: 


° Additional automatic call libraries, which contain modules 
used to resolve external references found in the program. 


e Restricted no-call function: External references that are 
not to be resolved by the automatic library call mechanism 
during the current linkage editor job step. 


e Never-call function: External references that are not to be 
resolved by the automatic library call mechanism during any 
linkage editor job step. 


Combinations of these functions can be written in the same 
LIBRARY statement. 


FORMAT: The format of the LIBRARY statement is: 


LIBRARY {ddname(membernamel,...]). 
(externalreferencel,...]) 


¥lexternalreferencel,...])},... 





ddname 


1s the name of a DD statement that defines a library. 


membername 


is the name of or an alias for a member of the specified 
library. Only those members specified are used to resolve 
references. 
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externalreference 
is an external reference that may be unresolved after 
primary input processing. The external reference is not to 
be resolved by automatic library call. 


indicates that the external reference is never to be 
resolved; if the * (asterisk) 15 missing, the reference is 
left unresolved only during the current linkage editor run. 


PLACEMENT: A LIBRARY statement can be placed before, between, or 
after object modules or other control statements. 


Notes: 


1. If the unresolved external symbol is not a member name in 
the library specified, the external reference remains 
unresolved unless defined in another input module. 


2. If the NCAL option is specified, the LIBRARY statement 
cannot be used to specify additional call libraries. 


3. Members called by automatic library call are placed in the 
root segment of an overlay program, unless they are 
repositioned with an INSERT statement. 


4. Specifying an external reference for restricted no-call or 
never-call by means of the LIBRARY statement prevents the 
external reference from being resolved by automatic 
inclusion of the necessary module from an automatic call 
library; it does not prevent the external reference from 
being resolved if the module necessary to resolve the 
reference 1s specifically included or is included as part of 
an input module. 


EXAMPLE: The following example shows all three uses of the 
LIBRARY statement: } 


// EXEC PGM=HEWL,PARM="LET,XREF,LIST'* 
//TESTLIB DD DSNAME=TEST,DISP=SHR,... 


//7SYSLIN DD x 


LIBRARY TESTLIBCDATE, TIME), CFICACOMP),*CSTATETAX) 
/¥ 





As a result, members DATE and TIME from the additional library 
TESTLIB are used to resolve external references. FICACOMP and 
STATETAX are not resolved; however, because the references 
remain unresolved, the LET option must be specified on the EXEC 
statement if the module is to be marked executable. ,In 
addition, STATETAX will not be resolved in any subsequent 
reprocessing by the linkage editor. 
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MODE Statement 


The MODE statement specifies the residence mode for the output 
load module and/or the addressing mode for all the entry points 
into the load module (the main entry point, its true aliases, 
and all the alternate entry points). 


FORMAT: The format of the MODE statement is as follows: 


MODE modespec(,modespec) 


modespec 
is either of the following: 


° The designation of an addressing mode for the output load 
module by one of the following: 


= AMODEC24) 
= AMODEC 31) 
= AMODECANY) 


e The designation of residence mode for the output load module 
by one of the following: 


= RMODEC24) 
= RMODECANY ) 


PLACEMENT: The MODE control statement can be placed before, 
between, or after object modules or other control statements. 
It must precede the NAME statement for the module, if one is 
present. 


Notes: 


1. The residence mode assigned by the MODE control statement 
overrides the residence mode accumulated from the input 
control sections and private code. The residence mode 
assigned by the MODE control statement also overrides the 
residence mode assigned by the RMODE parameter in the PARM 
field of the EXEC statement. 


2. The addressing mode assigned by the MODE control statement 
overrides the separate addressing modes found in the ESD 
data for the control sections within which the entry points 
are located. The addressing mode assigned by the MODE 
control statement overrides the addressing mode assigned by 
the AMODE parameter in the PARM field of the EXEC statement. 


3. If more than one MODE control statement is encountered in 
the link-edit of a load module, the last valid mode 
specification is used. Likewise, if a mode specification 
occurs more than once within a MODE statement, the last 
valid mode specification is used. 


4. If only one value, either AMODE or RMODE, is specified in 


the MODE control statement, the other value is implied 
according to the following table: 
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Value Specified 


If only an RMODE of 24 is specified, no overriding AMODE 
value 15 assigned; instead, the AMODE value in the ESD data 
for the main entry point, a true alias, or an alternate 
sg point is used in generating its respective directory 
entry. 


5. In generating a directory entry for either the main entry 
point, a true alias,» or an alternate entry point, the 
linkage editor validates the combination of the AMODE value 
and the RMODE value, as specified by the user in the MODE 
control statement(s), according to the table below: 


Lo dl RMODE=26 | RMODE=ANY 












6. If the AMODE/RMODE combination resulting from the MODE 
control statement(s) is invalid, an error message 1S issued 
and the linkage editor ignores the MODE control statement(s) 
as the source of AMODE/RMODE data. 


J 


EXAMPLE: In the following example, an output load module, named 
NEWMOD, is created; it is given a true alias of TESTMOD; the 
residence mode for the load module is ANY; the addressing mode 
for both the main entry point, NEWMOD, and the true alias, 
TESTMOD, is 31. 


//SYSLMOD DD DSN=TESTLOAD, DISP=MOD,... 
//SYSLIN DD x 


AMODE(31),RMODECANY) 
TESTMOD 
NEWMOD 
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NAME Statement 


The NAME statement specifies the name of the load module created 
from the preceding input modules, and serves as a delimiter for 
input to the load module. As a delimiter, the NAME statement 
allows multiple load module processing in one linkage editor job 
step. The NAME statement can also indicate that the load module 
replaces an identically named module in the output module 
library. 


FORMAT: The format of the NAME statement is: 


| NAME | membernameLl(R)] 


membername 


is the name to be assigned to the load module that 15 
created from the preceding input modules. 


(R) 
indicates that this load module replaces an identically 
named module in the output module library. If the module 
is not a replacement, the parenthesized value (R) should 
not be specified. 


PLACEMENT: The NAME statement is placed after the last input 
module or control statement that is to be used for the output 
module. 


Notes: 
1. Any ALIAS statement used must precede the NAME statement. 


2. A NAME statement found in a data set other than the primary 
input data set is invalid. The statement 1s ignored. 


EXAMPLE: In the following example, two load modules, RDMOD and 
WRIMOD, are produced by the linkage editor in one job step: 


//SYSLMOD DD DSNAME=AUXMODS,DISP=MOD,... 
//NEDIMOD DD DSNAME=&&WRTIMOD, DISP=OLD 
J/SYSLIN DD DSNAME=&&RDMOD, DISP=OLD 

// DD % 


NAME RDMODCR) 
INCLUDE NEWMOD 
NAME WRTIMOD 

7% 





As a result, the first module 1s named RDMOD and replaces an 
identically named module in the output module library AUXMODS; 
the second module 1s named WRIMOD and is added to the library. 
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ORDER Statement 


The ORDER statement indicates the sequence itn which control 
sections or named common areas appear in the output load module. 
The control sections or named common areas appear in the 
sequence in which they are specified on the ORDER statement. 
When multiple ORDER statements are used, their sequence further 
determines the sequence of the control sections or named common 
areas in the output load module; those named on the first 
statement appear first, and so forth. 


FORMAT: The format of the ORDER statement is: 


ORDER {common area namel(P)])|csectnamel(P)1},... 


common area name 


15 the name of the common area to be sequenced. 


csectname 


1s the name of the control section to be sequenced. 


(P) 
indicates that the starting address of the control section 
or named common area is to be on a page boundary within the 
load module. The control sections or common areas are 
aligned on 4K-byte page boundaries. 


PLACEMENT: An ORDER statement can be placed before, between, or 
after object modules or other control statements. 


Notes: 
1. A control section or common area can be named on only one 
ORDER statement. If the same name is used more than once, 


except when it is the last operand on one ORDER statement 
and the first operand on the next, the name 1s ignored, as 
is the balance of the control statement on which it appears. 


2. The control sections and common areas named as operands can 
appear in either the primary input or the automatic call 
library, or both. 


3. If a control section or a named common area is changed by a 
CHANGE or REPLACE control statement and sequencing is 
desired, specify the new name on the ORDER statement. The 
ORDER statement refers to the control section by its new 
name. 


EXAMPLE: In this example, the control sections in the load 
module LDMOD are arranged by the linkage editor according to the 
sequence specified on ORDER statements. The page boundary 
alignments and the control section sequence made as a result of 
these statements are shown in Figure 50 on page 129. Assume 
each control section is 1K byte in length. 
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JCL and Control Statements Output Load Module 


LDMOD 


° ROOTSEG 
//SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,... 
//SYSLIN DD * 
ORDER ROOTSEG(P) ,MAINSEG,SEG1 ,SEG2 
ORDER SEG3(P) , ENTRY1 
ORDER FSTPART ,SESECTA,SESECTB (P) 
INCLUDE SYSLMOD(LDMOD) 
/* 


MAINSEG 








SEG1 


SEG2 


4k 


SEG3 


ENTRY1 


FSTPART 


SESECTA 


8K 





SESECTB 





Figure 50. Output Load Module for ORDER Statement Example. The control section name 
PART1 is changed by a CHANGE statement to FSTPART. The ORDER statement 
refers to the control section by its new name. 
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OVERLAY Statement 


The OVERLAY statement indicates either the beginning of an 
overlay segment, or of an overlay region. Because a segment or 
a region is not named, the programmer identifies it by giving 
its origin Cor load point) a symbolic name. This name is then 
used on an OVERLAY statement to signify the start of a new 
segment or region. 


FORMAT: The format of the OVERLAY statement is: 


OVERLAY symbol (REGION ) 


symbol 
1s the symbolic name assigned to the origin of a segment. 
This symbol is not related to external symbols in a module. 


(REGION) 
specifies the origin of a new region. 


PLACEMENT: The OVERLAY statement must precede the first module 
of the next segment, the INCLUDE statement specifying the first 
module of the segment, or the INSERT statement specifying the 
control sections to be positioned in the segment. 


Notes: 


1. The OVLY option must be specified on the EXEC statement when 
OVERLAY statements are to be used. 


2. The sequence of OVERLAY statements should reflect the order 
of the segments in the overlay structure from top to bottom, 
left to right, and region by region. 

3. No OVERLAY statement should precede the root segment. 


EXAMPLE: The following OVERLAY and INSERT statements specify the 
overlay structure in Figure 51 on page 131. 


// EXEC PGM=HEWL,PARM="OVLY,XREF,LIST' 


//SYSLIN DD DSNAME=&&0OBJ,... 
// DD % 
INSERT CSA 
OVERLAY ONE 
INSERT CSB 
OVERLAY TWO 
INSERT CSC 
OVERLAY TWO 
INSERT CSD 
OVERLAY ONE 
INSERT CSE,CSF 
OVERLAY THREECREGION) 
INSERT CSH 
OVERLAY THREE 
INSERT CSI 





130 MVS/370 Linkage Editor and Loader 


J 


REGION 1 T 


CSA 
r ONE 

CSB CSE 

TWO Csi 

CSC a osfe. 
THREE 

REGION 2 oe a 


Figure 51. Overlay Structure for OVERLAY Statement Example 
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PAGE Statement 


The PAGE statement aligns a control section or named common area 
on a 4&K-byte page boundary in the load module. 


FORMAT: The format of the PAGE statement is: 


| PAGE {common area name|]csectname},... 


common area name 


is the name of the common area to be aligned on a page 
boundary. 


csectname 


1s the name of the control section to be aligned on a page 
boundary. 


PLACENENT: The PAGE statement can be placed before, between, or 
after object modules or other control statements. 


Notes: 


1. If a control section or a named common area is changed by a 
CHANGE or REPLACE control statement, and page alignment is 
wanted, specify the new name in the PAGE statement. 


2. The control sections and common areas named as operands can 
appear tin either the primary input or the automatic call 
library, or both. 


EXAMPLE: In this example, the control sections in the load 
module LDMOD are aligned on page boundaries as specified in the 
following PAGE statement: 


PAGE ALIGN, BNDRY4K,EIGHTK 
The job control statements and linkage editor control statements 


as Well as the output load module are shown in Figure 52 on page 
133. Assume each control section is 3K bytes in length. 
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JCL And Control Statements Output Load Module 


//LKED EXEC PGM=HEWL,PARM=,... LDMOD 


/ /SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,... 


//SYSLIN DD x 
PAGE ALIGN, BNDRY4K ,EIGHTK 
INCLUDE SYSLMOD (LDMOD) 

/* 


Empty Space 
Due to Boundary 
Alignment 


BNDRY4K 


Empty Space 
Due to Boundary 
Alignment 


EIGHTK 





Figure 52. Qutput Load Module for PAGE Statement Example 
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REPLACE Statement 


The REPLACE statement specifies one or more of the following: 


e The replacement of one control section with another 
e The deletion of a control section 
e The deletion of an entry name 


When a control section is replaced, all references within the 
input module to the old control section are changed to the new 
control section. Any external references to the old control 
section from other modules are unresolved unless changed. 


When a control section is deleted, the control section name is 
also deleted from the external symbol dictionary, unless 
references are made to the control section from within the input 
module. If there are any such references, the control section 
name 1s changed to an external reference. External references 
from other modules to a deleted control section also remain 
unresolved. 


When deleting an entry name, if there are any references to it 
within the same tnput module, the entry name is changed to an 
external reference. 


FORMAT: The format of the REPLACE statement is: 


REPLACE {csectname-1[ (csectname-2)],entryname} 


csectname 
is the name of a control section. If only csectname-1 is 
used, the control section 1s deleted; if csectname-2 is 
also used, the first control section is replaced with the 
second. 


entryname 
is the entry name to be deleted. 


PLACEMENT: The REPLACE statement must immediately precede either 
(1) the module containing the control section or entry name to 
be replaced or deleted, or (2) the INCLUDE statement specifying 
the module. The scope of the REPLACE statement is across the 
immediately following module Cobject module or load module). 

The END record in the immediately following object module or the 
end-of-module indication in the load module terminates the 
action of the REPLACE statement. If the REPLACE statement is 
the last control statement in the SYSLIN data set, and there are 
unresolved external references to be resolved from SYSLIB, the 
REPLACE function operates on the first module from SYSLIB by an 
AUTO CALL. 


Notes: 


1. Unresolved external references are not deleted from the 
output module even though a deleted control section contains 
the only reference to a symbol. 


2. When some but not all control sections of a separately 
assembled module are to be replaced, A-type address 
constants that refer to a deleted symbol will be incorrectly 
resolved, unless the entry name is at the same displacement 
from the origin in both the old and the new control 
sections. 


3. If no INCLUDE statement follows the REPLACE statement, one 
module may be left out of AUTO CALL. Message LEWO132 is 
issued. 


4. If the control section identified as csectname-l (specified 
on the REPLACE statement) is misspelled, the control section 
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will not be replaced or deleted. Linkage editor output, 
such as the cross-reference listing and module map, can be 
used to verify each change. 


EXAMPLE: In the following example, assume that control section 
INT7 is in member LOANCOMP and that control section INT&, which 
is to replace INT7, is in data set &&NEWINT. Also assume that 
control section PRIME in member LOANCOMP 1s to be deleted. 


//NEWMOD DD DSNAME=&&NEWINT,DISP=C(OLD, DELETE) 
7/0LDMOD DD DSNAME=PVTLIB,DISP=OLD,... 
//SYSLIN DD x 

ENTRY MAINENT 


INCLUDE NEWMOD 

REPLACE INT7CINT8),PRIME 

INCLUDE OLDMODCLOANCOMP ) 
1% 





As a result, INT? is removed from the input module described by 
the OLDMOD DD statement, and INT& replaces INT7. All references 
to INT7 in the input module now refer to INT&. Any references 
to INT? from other modules remain unresolved. If there are no 
references to PRIME in LOANCOMP, control section PRIME is 
deleted; the control section name is also deleted from the 
external symbol dictionary. 
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SETCODE Statement 


The SETCODE statement assigns the specified authorization code 
to the output load module. The authorization code is placed in 
the directory entry for the output load module. 


FORMAT: The format of the SETCODE statement is as follows: 


SETCODE ACCauthorizationcode) 


authorizationcode 


is 1 to 3 decimal digits specifying a value from 0 to 255. 


PLACEMENT: A SETCODE statement can be placed before, between, or 
after object modules or other control statements. It must 
precede the NAME statement for the module, if one is present. 


Notes: 


1. The authorization code assigned by the SETCODE statement 
overrides the authorization code assigned by the AC 
parameter in the PARM field of the EXEC statement. 


2. If more than one SETCODE statement is encountered in the 
link-edit of a load module, the last valid authorization 
code assigned is used. 


3. The operand "ACC )* results in an authorization code of 
zero. 


EXAMPLE: In the following example, an authorization code of 1 is 
assigned to the output load module MODI. 


//LKED PGM=HEWL 

//SYSPRINT SYSOUT=A 

//SYSUT1 UNIT=SYSDA,SPACE=C(TRK,(10,5)) 
//SYSLMOD DSNAME=SYS1.LINKLIB,DISP=OLD 
//SYSLIN DSNAME=&&LOADSET,DISP=COLD,PASS) 


UNIT=SYSDA 
% 

SETCODE AC(1) 

NAME MOD1CR) 
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SETSSI Statement 


The SETSSI statement specifies hexadecimal information to be 
placed in the system status index of the directory entry for the 
output module. 


FORMAT: The format of the SETSSI statement is: 


MX KKM KKK 


represents 8 hexadecimal characters (0 through 9 and A 
through F) to be placed in the 4-byte system status index 
of the output module library directory entry. 


PLACEMENT: The SETSSI statement can be placed before, between, 
or after object modules or other control statements. If one is 
present, it must precede the NAME statement for the module. 


Note: <A SETSSI statement must be provided whenever an 
IBM-supplied load module is reprocessed by the linkage editor. 
If the statement is omitted, no system status index information 
is present. 
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APPENDIX A. SAMPLE PROGRAMS 


This appendix contains sample linkage editor programs. The 
material presented for each program includes a description of 
the program, the job control language necessary for the linkage 
editor job step, linkage editor control statements (Cif any), and 
the linkage editor output. The sample programs are: 


° Link-editing a COBOL and a FORTRAN object module (COBFORT) 


e Replacing one control section with another by using the 
REPLACE statement (RPLACJOB) 


e Creating a multiple-region overlay program (CREGNOVLY) 


@ Placing the control statements for the multiple region 
overlay program ina partitioned data set, and using them 
CPARTDS) 


The output for each program includes a cross-reference table, a 
module map, a control statement listing, and diagnostic 
messages, if any. 


SAMPLE PROGRAM COBFORT 


Sample program COBFORT link-edits a COBOL object module and a 
FORTRAN object module to form one load module. The source 
programs were compiled in two steps previous to the linkage 
editor job step, and the output from each compilation was placed 
in data set &&OBJMOD. 


Job Control Language 2 


The job control language for the linkage editor job step of this 
sample program is: 


//LKED PGM=HEWL,PARM='"XREF’ 

//SYSUTI DSNAME=&&UT1,UNIT=SYSDA,SPACE=CTRK, 
// €100,10)) 

//SYSLIB DSNAME=SY51.COBLIB,DISP=SHR 

47 D DSNAME=SYS1.FORTLIB,DISP=SHR 


//SYSLMOD DSNAME=&&LOADMD(GO),UNIT=SYSDA, 
1/7 DISP=(NEW,PASS),SPACE=CTRK, 

// €100,10,1)) 

//SYSPRINT SYSOUT=A 

/7SYSLIN DSNAME=-&&OBJMOD, DISP=COLD, DELETE) 
7% 





Statement Explanation 


EXEC Causes the execution of the linkage editor. The 
PARM field option requests a cross-reference table 
and a module map to be produced on the diagnostic 
output data set. 


SYSUTI1 Defines a temporary direct access data set to be 
used as the intermediate data set. 
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SYSLIB Defines the automatic call library; the call 
libraries for COBOL and FORTRAN are concatenated; 
both are used to resolve external references. 


SYSLMOD Defines a temporary data set to be used as the 
output module library; the load module is assigned a 
member name of GO, and is passed to a subsequent 
step for execution. 


SYSPRINT Defines the diagnostic output data set, which is 
assigned to output class A. 


SYSLIN Defines the primary input data set, &&0BJMOD, which 
contains both input object modules; this data set 
was passed from a previous job step and is to be 
deleted at the end of this job step. 


Linkage Editor Output 


Figure 53 on page 140 shows the linkage editor output for 
COBFORT. The listing header indicates the options specified 
CXREF), and the SIZE option values in decimal (196608 for valuel 
and 65536 for value2). Because XREF is specified, the heading 
CROSS REFERENCE TABLE precedes the rest of the output. 


Figure 53 also shows the module map for COBFORT. IPCT30 and 
TX652F are the names of the input control sections. The rest of 
the control sections are either from the COBOL automatic call 
library or from the FORTRAN automatic call library. (They can 
be distinguished by the initial three letters; ILB indicates a 
COBOL control section, IHC a FORTRAN control section.) The 
origin and length Cin hexadecimal) of each control section 
follow the name. 


To the right of each control section is a list of the entry 
names defined in each control section. The location (Cin 
hexadecimal) of each entry name is also given. For example, in 
control section IHCCOMH2 (the asterisk is not a part of the 
name; it indicates that the control section is from the 
automatic call library), entry name SEQDASD is defined at 
location 154A. 


Figure 53 shows the cross-reference table for COBFORT. The 
table contains the location of any address constant that refers 


to a symbol defined in another control section. The symbol the 
address constant refers to is also listed, along with the 
control section tn which the symbol is defined. For example, at 


location 1F0 in control section IPCT30 (determined by using the 
module map; I1F0O falls between origin 00 and origin 360), an 
address constant refers to symbol IHDFDISP, defined in control 
section IHDFDISP. 


The entry address is 00 and the total length of the load module 
is 4AE8. Note that the length of the module is rounded up to a 
doubleword boundary. 


The disposition message at the end of the output in Figure 53 
indicates that the load module GO has been added to the output 
module library. The library did not contain any other module 
with that name. The four asterisks identify the message. 


SAMPLE PROGRAM RPLACJOB 


Sample program RPLACJOB shows the use of the REPLACE statement 
to replace one control section with another. The source program 
for the new control section (NEWMOD) is processed in a previous 
job step and passed to the linkage editor job step. The control 
section (SUBONE) to be replaced is in an existing load module. 
Figure 54 on page 141 shows the linkage editor output for the 
job step that created this load module. Note that the entry 
address is F0, which is the location of the entry point MAINMOD 
(specified on the ENTRY control statement). 
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Hodule Map 


Cross-Reference Table 


Figure 53. 
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F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF 
DEFAULT OPTIONS(S) USED - SIZE=(196608,65536) 


CONTROL SECTION 


NAME 


IPCT30 
TX652F 
IHCFCOMH* 


IHCCOMH2* 


IHDFDISP®* 
IHCFCVTH® 


IHCFINTH*® 


IHCFIOSH* 


IHCUOPT * 
IHCTRCH * 


IHCUATBL® 


LOCATION 
1F0 
410 

1108 
110¢€ 
1128 
1114 
111¢ 
1124 
10E4 
14AC 
1264 
2c78 
3120 
30D0 
3124 
3FF8 
43D0 
43D8 


ORIGIN 


00 
360 
540 

1220 
1658 
1¢080 
2E20 


31C0 


41D0 
41D8 


44B0 


LENGTH 


360 
1EO 
cb9 
434 
626 
119D 


39E 


100E 


2D4 


638 


REFERS TO SYMBOL 


ENTRY ADDRESS 
TOTAL LENGTH 


#088G0 


IHDFDISP 
IBCOM# 
ADCON# 
ARITH# 
IHCUOPT 
FCVLOUTP 
FCVCOUTP 
FCVZOUTP 
IHCERRM 
IHCFCOMH 
IBCOM# 
IHCERRM 
INTSWTCH 
IHCUOPT 
FIOCS# 
IHCUATBL 
IBCOM# 
FIOCS# 


00 
4AE8 


AUTHORIZATION CODE IS 
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Linkage Editor Output for Sample Program COBFORT 


IN CONTROL SECTION 


QO. 


ENTRY 
NAME 


IBCOM# 


SEQDASD 


ADCON# 
FCVIOUTP 


ARITH# 


FIOCS# 


IHCERRM 


IHDFDISP 
IHCFCOMH 
IHCFCVTH 
IHCFINTH 
IHCUOPT 

IHCFCVTH 
THCFCVTH 
IHCFCVTH 
IHCTRCH 

ITHCFCOMH 
IHCFCOMH 
IHCTRCH 

IHCFCOMH 
THCUOPT 

THCFIOSH 
IHCUATBL 
IHCFCOMH 
IHCFIOSH 


LOCATION 


540 


154A 


1c80 


22B8 


2E20 


31¢c0 


41D8 


CROSS REFERENCE TABLE 


NAME 


FDIOCS# 


FCVAOUTP 
FCVEOUTP 


ADJ SWTCH 


LOCATION 
1F4 
5FC 

1100 
112¢ 
1110 
1118 
1120 
10E0 
14A9 
1268 
2Cc7C 
311¢ 
30D4 
3128 
32F8 
4004 
43D4 


DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 


REFERS TO SYMBOL 


TX652F 
SEQDASD 
FIocs# 
ADJSWTCH 
FCVEOUTP 
FCVIOUTP 
FCVAOUTP 
IHCCOMH2 
IHCFCOMH 
IHCERRM 
IBCOM# 
IBCOM# 
INT6SWCH 
ADCON# 
IHCERRM 
IBCOM# 
ADCON# 


NAME LOCATION 
INTSWTCH 11FE 
FCVLOUTP 1DBA 
FCVCOUTP 29D4 


NAME 


FCVZOUTP 
INT6SWCH 


TX652F 
IHCCOMH2 
IHCFIOSH 
IHCFINTH 
IHCFCVTH 
IHCFCVTH 
IHCFCVTH 
IHCCOMH2 
IHCFCOMH 
IHCTRCH 
IHCFCOMH 
IHCFCOMH 
IHCFCVTH 
IHCFCVTH 
IHCTRCH 
IHCFCOMH 
IHCFCVTH 


LOCATION 


1FOA 
2CBB 


IN CONTROL SECTION 


c 


F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF,LIST 
DEFAULT OPTION(S) USED - SIZE=(196608,65536) 


TEWO000 ENTRY MAINMOD 


CROSS REFERENCE TABLE 


CONTROL SECTION ENTRY 


NAME ORIGIN LENGTH NAME LOCATION 
SUBONE 00 EF 
SuB1 00 
MAINMOD FO 146 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
11c SUBONE SUBONE 
ENTRY ADDRESS FO 
TOTAL LENGTH 238 
$9838G0 DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 
AUTHORIZATION CODE IS QO. 
Figure 54. 


LOCATION NAME LOCATION NAME LOCATION 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION 


Linkage Editor Output for Job Step that Created SUBONE 





Job Control Language 


The job control language for the replacement job step of this 
sample program is shown below. 


//LKED 
//SYSUTI1 
//TNPUTX 
// 
7/SYSLMOD 
// 


//SYSPRINT 
//SYSLIN 

// 

// DD 


PGM=HEWL,PARM="XREF,LIST* 
UNIT=SYSDA,SPACE=CTRK, (100,10)) 
DSNAME=LOADLIB,DISP=OLD,UNIT=SYSDA, 
VOL=SER=SCRTCH 
DSNAME=LOADLIBCGO),DISP=OLD,UNIT=SYSDA, 
VOL=SER=SCRITCH 

SYSOUT=A 
DSNAME=&&OBJMOD,DISP=COLD, DELETE), 
UNIT=SYSDA 

% 


Linkage Editor Control Statements 


7% 
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Statement 
EXEC 


SYSUT1 


INPUTX 


SYSLMOD 


SYSPRINT 


SYSLIN 


Figure 55. 


Explanation 


Causes the execution of the linkage editor. The PARM 
field options request a cross-reference table anda 
module map (XREF), and a control statement listing 
CLIST) to be produced on the diagnostic output data 
set. 


Defines a temporary direct access data set to be 
used as the intermediate data set. 


Defines a permanent data set, used later as 
additional linkage editor input. 


Defines a permanent data set to be used as the 
output module library. Note that it is the same data 
set that was described on the INPUTX DD statement. 
The output load module is added to the data set, 
under the member name GO. 


Defines the diagnostic output data set, which is 
assigned to output class A. 


Defines the primary input data set, &&OBJMOD, which 
contains the object module for the replacement 
control section. This data set is temporary and was 
passed from a previous job step; it is to be deleted 
at the end of this job. This statement also 
concatenates the input stream to the primary input 
data set. The input stream contains linkage editor 
control statements that must be followed by a /x 
statement. 


Job Control Statements for RPLACJOB 


LINKAGE EDITOR CONTROL STATEMENTS 


The input stream contains the linkage editor control statements 
that are necessary for the replacement of SUBONE with NEWMOD. 
The control statements are shown below: 


ENTRY 
REPLACE 
INCLUDE 


Statement 
ENTRY 
REPLACE 


INCLUDE 


Figure 56. 


MAINMOD 
SUBONECNEWMOD) 
INPUTX(GO) 


Explanation 
Specifies that the entry point is to be MAINMOD. 


Specifies that control section SUBONE in the module 
that follows the REPLACE statement is to be replaced 
by control section NEWMOD. 


Specifies additional input: member GO of the data 
set described on the INPUTX DD statement. This 
library member contains the control section to be 
replaced. Because this member name is identical to 
that specified on the SYSLMOD DD statement, the 
output load module replaces the existing library 
member. 


Linkage Editor Control Statements for RPLACJOB 
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Linkage Editor Output 


Figure 57 shows the linkage editor output for sample program 

RPLACJOB. The listing header indicates the options specified 
CXREF and LIST), and the SIZE option values used (196608 for 

valuel and 65536 for value2). 


F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF,LIST 


DEFAULT OPTION(S) USED - SIZE=(196608,65536) 
IEwOO00 ENTRY MAINMOD 
IEwOO0O REPLACE SUBONE (NEWMOD) 
IEwOO00 INCLUDE INPUTX (GO) 
CROSS REFERENCE TABLE 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 

NEWMOD 00 Fl 

MA INMOD FS 146 

LOCATION REFERS TO SYMBOL IN CONTROL SECTION LOCATION REFERS TO SYMBOL IN CONTROL SECTION 

124 NEWMOD NEWMOD 

ENTRY ADDRESS F8 

TOTAL LENGTH 240 
$#66G0 NOW REPLACED IN DATA SET 
AUTHORIZATION CODE IS Q. 


Figure 57. Linkage Editor Output for Sample Program RPLACJOB 


Because the LIST option is specified, a control statement 
listing is produced. Each control statement is preceded by a 
special message number, IEW0000. Because XREF is specified, the 
heading CROSS REFERENCE TABLE precedes the rest of the output. 


The module map shows that control section NEWMOD is now part of 
the load module, and that control section SUBONE has been 

deleted. The new entry address is F8&8, because NEWMOD is longer 
than SUBONE. The total length of the load module is 240 bytes. 


The cross-reference table indicates that at location 124 in 
MAINMOD, an address constant refers to symbol NEWMOD, defined in 
control section NEWMOD. Note that before the replacement 
occurred, the address constant in MAINMOD referred to SUBONE, 
defined in control section SUBONE (Figure 54 on page 141). When 
the REPLACE statement is used to replace a control section, 
references to the old control section from within the same input 
module are also changed. 


The disposition message indicates that the output load module 
(GO) has been added to the output module library. 


SAMPLE PROGRAM REGNOVLY 


Sample program REGNOVLY creates a multiple-region overlay 
structure. The structure produced is shown in Figure 58 on page 
144. In this program, some of the references between control 
sections are: 

CSA to CSE 

CSB to CSE 

CSB to CSD 

CSD to CSC 


The reference from CSB to CSE is a valid exclusive call, because 
there is a reference to CSE in the segment common to both CSB 
and CSE; the reference from CSD to CSC is invalid, because there 
is no reference to CSC in the common segment. 
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REGION 1 


CSA Root Segment | 







Alpha 
Segment 2 CSE Segment 5 
CSC Segment 3 CSD Segment 4 
REGION 2 Gamma 
CSF Segment 6 CSG Segment 7 


Hi I 


Figure 58. Overlay Tree for Multiple-Region Sample Program REGNOVLY 


The source programs for all the control sections were compiled 
in previous job steps. All the object modules were placed in 


the same data set, which was passed to the linkage editor job 
step. 


Job Control Language 


The job control language for the linkage editor job step of this 
sample program 1s shown below. 
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C 


//LKED 
//SYSUTI 
// 
//SYSLIB 
//SYSLMOD 


47 
//SYSPRINT 
//SYSLIN 
47 


EXEC PGM=HEWL,PARM='XREF,LIST,OVLY,LET' 

DD DSNAME=&&UT1,UNIT=SYSDA,SPACE=CTRK, 
€100,10)) 

DD DSNAME=SYS1.COBLIB,DISP=SHR 

DD DSNAME=&&OVLYJB(GO),UNIT=SYSDA, 
DISP=(NEW,PASS),SPACE=(TRK,(100,10,1)) 

DD SYSOUT=A 

DD DSNAME=&&OBJMOD, DISP=C(OLD, DELETE) 

DD x 


Linkage Editor Control statements 


7% 


Statement 
EXEC 


SYSUTI 


SYSLIB 


SYSLMOD 


SYSPRINT 


SYSLIN 


Figure 59. J 





Explanation 


Causes the execution of the linkage editor. The 
PARM field options request a cross-reference table 
and a module map (XREF), and a control statement 
listing (LIST) to be produced on the diagnostic 
output data set. The module is to be assigned the 
overlay attribute (OVLY), and marked executable in 
spite of severity 2 errors (LET). The LET option is 
specified to permit testing of the output module, 
even though an invalid exclusive call is present. 
The XCAL option allows only valid exclusive calls. 


Defines a temporary direct access data set to be 
used as the intermediate data set. 


Defines the automatic call library (SYS1.COBLIB) to 
be used to resolve external references. All control 
sections from this library are placed in the root 
segment; they remain there unless they are 
repositioned. 


Defines a temporary data set to be used as the 
output module library; the load module is assigned 
the member name GO and is passed to a subsequent 
step for execution. 


Defines the diagnostic output data set, which is 
assigned to output class A. 


Defines the primary input data set, &&0BJMOD, which 
contains the object modules for the overlay 
structure. This data set is temporary and was 
passed from a previous job step; it is to be deleted 
at the end of this job. This statement also 
concatenates the input stream to the primary input 
data set. The input stream contains linkage editor 
control statements, which must be delimited by a /* 
statement. 


ob Control Statements for REGNOVLY 


Linkage Editor Control Statements 


The input stream contains the linkage editor control statements 
that structure the overlay program. The control statements are: 


INSERT CSA 


ENTRY CSA 


OVERLAY ALPHA 


INSERT CS 


B 
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OVERLAY BETA 

INSERT CSC 

OVERLAY BETA 

INSERT CSD 

OVERLAY ALPHA 

INSERT CSE 

OVERLAY GAMMACREGION) 
INSERT CSF 

OVERLAY GAMMA 

INSERT CSG 


Linkage Editor Output 


Figure 60 on page 147 shows the linkage editor output for sample 
program REGNOVLY. The list header indicates the options 
specified and the SIZE option values used. 
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F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF,LIST,OVLY, LET 


IEWOO0O 
IEWOOOO 
TEWOOOO 
IEWOO0O 
IEWOOO0O 
IEwOO0O 
IEWOOOO 
IEWOOO0O 
IEWOO0O 
IEWOOO0O 
IEWOOO0O 
IEWOO0O 
IEWOOO0O 
IEWOOO0O 
IEWO172 
IEWO1B82 


DEFAULT OPTION(S) USED - SIZE=(196608,65536) 


INSERT CSA 
ENTRY CSA 
OVERLAY ALPHA 
INSERT CSB 
OVERLAY BETA 
INSERT CSC 
OVERLAY BETA 
INSERT CSD 
OVERLAY ALPHA 
INSERT CSE 
OVERLAY GAMMA (REGION) 
INSERT CSF 
OVERLAY GAMMA 
INSERT CSG 
2 CSE 
4 CSC 


CROSS REFERENCE TABLE 


Root Segment 1: 


CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH’ SEG. NO. NAME LOCATION 
$SEGTAB 00 34 1 
CSA 38 366 1 
ILBODSPO* 3A0 6F8 1 
ILBOSTPO* A98 35 1 
ILBOSTP 1 AAE 
$ENTAB ADO 30 1 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
2co ILBODSPO ILBODSPO 1 
2cB CSG CSG 7 
2D0 CSB CSB 2 
Segment 2: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION 
CSB BOO 360 2 
$ENTAB E60 18 2 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
D54 ILBODSPO ILBODSPO 1 
D58 CSE CSE 5 
D5C CSD CSD 4 
Segment 3: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION 
csc E78 336 3 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
10cCc ILBODSPO ILBODSPO 1 
10D0 ILBOSTP1 ILBOSTPO 1 
Segment 4: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION 
CSD E78 362 4 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
10cC ILBODSPO ILBODSPO 1 
10D4 ILBOSTP 1 ILBOSTPO 1 


Figure 60 (Part 1 of 2). 


NAME LOCATION NAME LOCATION NAME 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
2c4 ILBOSTPO ILBOSTPO 
2cc CSE CSE 
2D4 ILBOSTP 1 ILBOSTPO 
NAME LOCATION NAME LOCATION NAME 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION 


D50 ILBOSTPO ILBOSTPO 

p60 ILBOSTP 1 ILBOSTPO 
NAME LOCATION NAME LOCATION NAME 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION 

10C8 ILBOSTPO ILBOSTPO 
NAME LOCATION NAME LOCATION NAME 


LOCATION REFERS TO SYMBOL 
10C8 ILBOSTPO 
10D0 csc 


IN CONTROL SECTION 
ILBOSTPO 
cSC 


LOCATION 


SEG. NO. 


LOCATION 


SEG. NO. 


LOCATION 


SEG. NO. 


LOCATION 


SEG. NO. 


Linkage Editor Output for Sample Program REGNOVLY 
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CROSS REFERENCE TABLE 


Segment 5: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
CSE BOO 336 5 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
D54 ILBODSPO ILBODSPO 1 D50 ILBOSTPO ILBOSTPO 1 
DS8 ILBOSTP1 ILBOSTPO 1 
Segment 6: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
CSF 11E0 2FA 6 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
1430 ILBOSTPO ILBOSTPO 1 1434 ILBOSTP1 ILBOSTPO 1 
Segment 7: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
CSG 11E0 336 7 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
1434 ILBODSPO ILBODSPO 1 1430 ILBOSTPO ILBOSTPO 1 
1438 ILBOSTP1 ILBOSTPO 1 
ENTRY ADDRESS 38 
TOTAL LENGTH 1518 
ee684G0 DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 
AUTHORIZATION CODE IS 0. 


DIAGNOSTIC MESSAGE DIRECTORY 
IEWO172 ERROR - EXCLUSIVE CALL FROM SEGMENT NUMBER PRINTED TO SYMBOL PRINTED. 
IEWO182 ERROR - INVALID EXCLUSIVE CALL FROM SEGMENT NUMBER PRINTED TO SYMBOL PRINTED. 


Figure 60 (Part 2 of 2). Linkage Editor Output for Sample Program REGNOVLY 


Because the LIST option was specified, the control statement 
listing 1s produced. Each control statement is preceded by a 
special message number, IEWOO000. 


The control statement listing is followed by two diagnostic 
message numbers (IEWO172 and IEW0182). The explanation of the 
messages and the information following each message are given at 
the end of the output in the diagnostic message directory. 


The output for each segment contains a module map and a 
cross-reference table. The segments are listed as they appear 
in the overlay structure, top to bottom, left to right, and 
region by region. (Note that this is also the sequence in which 
the OVERLAY and INSERT statements must be given.) 


Within each segment, a module map lists the control sections in 
ascending sequence according to their assigned origin. The 
origin, length, and segment number are listed for each control 
section, along with any entry names and the location at which 
each entry name is defined. For example, the root segment has 
five control sections: S$SEGTAB, which is always the first 
control section in the root segment; CSA, which is from the 
object module input; ILBODSPO and ILBOSTPO, which are from the 
automatic call library Cindicated by an asterisk) and were not 
repositioned; and SENTAB, which, when present, is always the 
last control section in any segment (as also in segment 2). One 
entry name is defined, ILBOSTP1 at location D58 in control 
section ILBOSTPO. 


The cross-reference table for each segment contains all the 
address constants that refer to symbols defined in other control 
sections. The location of the address constant is followed by 
the symbol referred to, the control section in which the symbol 
is defined, and the segment in which the control section is 
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located. For example, in the root segment, an address constant 
at location 11E0 refers to symbol CSG, which is defined in 
control section CSG in segment 7. Although the region is not 
given, the overlay tree in Figure 58 on page 144 shows that 
segment 7 is in region 2. 


At the end of the output for all the segments are the entry 
address and total length. The entry address is 38, which is the 
origin of CSA, the specified entry point. The total length 
given refers to main storage used, not device storage. The 
length given, therefore, is that of the longest path. The 
longest path is that formed by the root segment and segments 2, 
4, and 7; the length given is 1518. 


However, if the given lengths of the control sections in each 
segment are added, the result is 14D3. The discrepancy exists 
because the given lengths do not include the padding bytes 
necessary to make control sections begin on a doubleword address 
(multiple of 8). For example, in the root segment, the length 
of SSEGTAB is 34; however, the origin of CSA which follows 
SSEGTAB is 38 (decimal 56). Four additional bytes are needed so 
that the origin of CSA is a multiple of 8. 


The disposition message indicates that the load module GO has 
been added to the output module library. The library did not 
contain any other module by that name. The four asterisks 
identify the message. 


The last item in the output for this sample program is the 
diagnostic message directory. The directory contains the text 
for the message numbers listed after the control statement 
listing. The directory must be correlated to the information 
following the number to interpret the message. 


For example, message IEW0172 is an error message that indicates 
that an exclusive call was made from the segment number printed 
(2) following the message number to the symbol printed (CSE). 
The output for segment 2 indicates that this call is at location 
D58 in control section CSB, and the symbol is defined in control 
section CSE in segment 5. This is the valid exclusive call from 
CSB to CSE described earlier. (If XCAL were specified, a 
warning message would be issued instead of an error message. ) 


If an invalid exclusive call is detected, message IEW0182 
appears as shown. This 1s also an error message; it indicates 
that an invalid exclusive call was made from segment 4 to symbol 
csc. This call is at location E78 in control section CSD, and 
the symbol is defined in control section CSC in segment 3. This 
is the invalid exclusive call from CSD to CSC, also described 
earlier. 


SAMPLE PROGRAM PARTDS 


Sample program PARTDS illustrates that linkage editor control 
statements can be placed in a separate data set and then used as 
input. For convenience, the control statements are those for 
sample program REGNOVLY, described previously. These control 
statements are placed ina partitioned data set. When the 
member that contains the control statements is referenced, the 
linkage editor uses the control statements to produce the 
overlay structure shown in Figure 58 on page 144. 


Figure 61 on page 150 shows the input statements for the 


IEBUPDTE utility program used to place the control statements in 
a partitioned data set. 
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//PARTDS JOB (accounting information) 
//CTLG EXEC PGM=IEBUPDTE, PARM=( NEW ) 
//SYSUT2 DD DSNAME=OVLYLIB, UNIT=2314, VOL=SER=DA028,DISP=(NEW,KEEP), 


LT 


SPACE=( TRK,(10,5,2)),DCB=( LRECL=80, BLKSIZE=80, RECFM=F ) 


//SYSPRINT DID SYSOUT=A 
//SYSIN DD * 


f 
/ 


ADD NAME=OVLY , LEVEL=00 , SOURCE=00, LIST=ALL 
NUMBER NEW1=10, INCR=5 


INSERT CSA 
ENTRY CSA 
OVERLAY ALPHA 
INSERT CSB 
OVERLAY BETA 
INSERT CSC 
OVERLAY BETA 
INSERT CSD 
OVERLAY ALPHA 
INSERT CSE 
OVERLAY GAMMA( REGION ) 
INSERT CSF 
OVERLAY GAMMA 
INSERT CSG 


-/ 
/* 


ENDUP 


Figure 61. Input Statements for IEBUPDTE Utility Program 


The source programs for all the control sections were compiled 
in previous job steps. All the object modules were placed in 
the same data set, which was passed to the linkage editor job 
step. The input modules are those used for sample program 
REGNOVLY. 


Job Control Language 


150 


The job control language for the overlay program job step of 
this sample program is shown below. 


//LKED PGM=HEWL,PARM="XREF,LIST,OVLY,LET' 
//SYSUT1 DSNAME=&&UT1,UNIT=SYSDA,SPACE=CTRK, 
// €100,10)) 

//OVLYCDS DD DSNAME=OVLYLIB,UNIT=SYSDA, 

1/ VOL=SER=SCRTCH, DISP=OLD 

//SYSLIB DD DSNAME=SYS1.COBLIB,DISP=SHR 
//7SYSLMOD DD DSNAME=&&OVLYJB(CGO),UNIT=SYSDA, 


7 DISP=CNEW,PASS),SPACE=CTRK,(100,10,1)) 
//SYSPRINT DD SYSOUT=A 

//SYSLIN DD DSNAME=&&OBJMOD, DISP=COLD, DELETE) 

7 DD x 


CLinkage Editor Control Statements) 
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Statement Explanation 


EXEC Causes the execution of the linkage editor. The PARM 
field options request a cross-reference table and a 
module map CXREF), and a control statement listing 
CLIST) to be produced on the diagnostic output data 
set. The output load module is to be assigned the 
overlay attribute (OVLY), and is to be marked 
executable despite severity 2 errors (LET). 


SYSUTI1 Defines a temporary direct access data set to be 
used as the intermediate data set. 


OVLYCDS Defines a permanent data set to be used later as 
additional input; this is the partitioned data set 
which was created by IJEBUPDTE and contains the 
control statements for structuring the overlay 


program. 
SYSLIB Defines the automatic call library (CSYS1.COBLIB) to 
be used to resolve external references. All control 


sections from this library are placed in the root 
segment; they remain there unless they are 
repositioned. 


SYSLMOD Defines a temporary data set to be used as the 
output module library; the load module is to be 
assigned the member name GO, and is passed to a 
subsequent step for execution. 


SYSPRINT Defines the diagnostic output data set, which 15 
assigned to output class A. 


SYSLIN Defines the primary input data set, &&OBJMOD, which 
contains the object modules for the overlay 
structure. This data set 1s temporary and was 
passed from a previous job step; it is to be deleted 
at the end of this job. This statement also 
concatenates the input stream to the primary input 
data set. The input stream contains linkage editor 
control statements that must be delimited by a /* 
statement. 


Figure 62. Job Control Statements for PARTDS 


Linkage Editor Control Statements 

The input stream contains an INCLUDE statement, as follows: 
INCLUDE OVLYCDSCOVLY) 

This statement causes the control statements to be read from the 
partitioned data set described on the OVLYCDS DD statement. The 
member name of the statements is OVLY, the same name used in the 
ADD statement for the utility program. 

Linkage Editor Output 
The output of this sample program is identical to the output 
from the REGNOVLY sample program, with one exception. The list 
of control statements begins with the statement 


IEWOO00 INCLUDE OVLYCDSCOVLY) 


This statement is followed by a list of the control statements 
read from the additional input data set specified in this 
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INCLUDE statement. The rest of the output is identical to that 
shown itn Figure 60 on page 147. ) 
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APPENDIX B. INVOKING THE LINKAGE EDITOR 


C 


The linkage editor can be invoked by a problem program at 
execution time through the use of one of the following macro 
instructions. 


[symbol] [LINK] EP=linkeditname 


PARAM=(CoptionlistI,ddname list]), 
VL=1 


[symbol] [ATTACH] EP=linkeditname 


PARAM=(optionlistI[,ddname list]), 


VL=1 


[symbol ] [LOAD] EP=linkeditname 


[symbol] [XCTL] EP=linkeditname 





wm EP= linkeditname 
specifies the symbolic name of the linkage editor. The 
entry point at which execution is to begin is determined 
by the control program (from the library directory entry). 
Any of the symbolic names that can be used as operands of 
the EXEC command's PGM parameter are acceptable as the 
"lLinkeditname™. 


PARAM=(Coptionlist[,ddname list]) 
specifies, as a sublist, address parameters to be passed 
from the problem program to the linkage editor. The first 
fullword in the address parameter list contains the 
address of the option and attribute list for the load 
module. The second fullword contains the address of the 
ddname list. If standard ddnames are to be used, this 
list may be omitted. 


optionlist 
specifies the address of a variable-length list 


containing the options and attributes. This address 
must be written even though no list is provided. 


The option list must begin on a halfword boundary. 
The 2 high-order bytes contain a count of the number 
of bytes in the remainder of the list. If no options 
or attributes are specified, the count must be zero. 
The option list is free form, with each field 
separated by a comma. No blanks or zeros should 
appear in the list. 


ddname list 
specifies the address of a variable-length list 
containing alternative ddnames for the data sets used 
¢ during linkage editor processing. If standard 
ddnames are used, this operand may be omitted. 
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The ddname list must begin on a halfword boundary. 
The 2 high-order bytes contain a count of the number 
of bytes in the remainder of the list. Each name of 
less than 8 bytes must be left justified and padded 
with blanks. If an alternate ddname is omitted from 
the list, the standard name will be assumed. If the 
name is omitted within the list, the &-byte entry 
must contain binary zeros. Names can be omitted from 
the end by merely shortening the list. 


The sequence of the &-byte entries in the ddname list 
15 as follows: 


Alternate Name For: 
SYSLIN 


Member name (the name under 
which the output load module 
is stored in the SYSLMOD data 
set; this entry is used if the 
name 1s not specified on the 
SYSLMOD DD statement or if 
there is no NAME control 
statement) 










SYSLMOD 


SYSLIB 


SYSTERM 













specifies that the sign bit is to be set to i in the last 
fullword of the address parameter list. 


When the linkage editor completes processing, a condition code 


is returned in register 15 (€see Figure 42 on page 100 for a 
list of linkage editor return codes). 
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APPENDIX C. STORAGE REQUIREMENTS AND CAPACITIES 


Capacities 





This appendix describes the record-processing capacities of the 
linkage editor, the types of devices that can be used for the 
intermediate data set (SYSUT1), and the amount of virtual 
storage the linkage editor requires. 


The minimum storage requirement and processing capacities of 
the linkage editor program are described in Figure 59 on page 
145. To increase the capacity for processing external symbol 
dictionary records, intermediate text records, relocation 
dictionary records, and identification records, increase valuel 
and/or value2 of the SIZE option. Output text record length 
can be increased by increasing the SIZE option values, but in 
no case may the record length ever exceed the lowest track 
length for the device or 18K bytes. The number of overlay 
segments and regions that can be processed is not affected by 


Increasing the storage available. 
Capacity 
(Bytes) 
Virtual storage allocated (Cin bytes) 
Maximum number of entries in composite external 558 
symbol dictionary (CESD) 
Maximum number of intermediate text records 


Maximum number of relocation dictionary (RLD) 192 
records 


Maximum number of segments per program 
Maximum number of overlay regions per program 
oo 

Figure 63 (Part 1 of 2). Linkage Editor Capacities for Minimal 


Maximum blocking factor for input object modules 
SIZE Values (96K bytes, 6K bytes) 



















object modules (number of 80-column card images 
per physical record) 










Maximum blocking factor for SYSPRINT output 
Cnumber of 121i-character logical records per 
physical record) 
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Capacity 
Function (Bytes ) 


Output text record length (in bytes): 


On IBM 2305-1 Fixed Head Storage Facility 
IBM 2305-2 Fixed Head Storage Facility 
IBM 2314 Storage Control Facility 
IBM 2319 Disk Storage Facility 
IBM 3330 Disk Storage Facility 
IBM 3330-11 Disk Storage Facility 
IBM 3340 Disk Storage Facility 
IBM 3344 Direct Access Storage Device 
IBM 3350 Direct Access Storage Device 
IBM 3375 Direct Access Storage Device 


IBM 3380 Direct Access Storage Device 





Figure 63 (Part 2 of 2). Linkage Editor Capacities for Minimal 
SIZE Values (96K bytes, 6K bytes) ) 


Note to Figure 63: 


1 The maximum output text record length is achieved when 
value2 of the SIZE parameter is at least twice the record 
length size. For example, on a 3330, 12288 byte records are 
written when value2 is at least 24576. 


For the composite external symbol dictionary, the number of 
entries permitted can be computed by subtracting, from the 
maximum number given in Figure 63 on page 155, one entry for 
each of the following: 


e A data definition name (ddname) specified in LIBRARY 
statements 


e A data definition name (Cddname) specified in INCLUDE 
statements 


e An ALIAS statement 


e A symbol in REPLACE or CHANGE statements that are in the 
largest group of such statements preceding a single object 
module in the input to the linkage editor 


® The segment table (SEGTAB) in an overlay program 
® An entry table CENTAB) in an overlay program 


To compute the number of intermediate text records that will be 
produced during processing of either program, add one record 

for each group of x bytes within each control section, where x 

1s the record size for the intermediate data set. The minimum 

value for x is 1024; a maximum is chosen depending on the ) 
amount of storage available to the linkage editor and the 

devices allocated for the intermediate and output data sets. 
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The number of intermediate text records that can be handled by 
a linkage editor program is less than the maximums given in 
Figure 63 on page 155 if the text of one or more control 
sections 1s not in sequence by address in the input to the 
linkage editor. 


The total length of the data fields of the CSECT identification 
records associated with a load module cannot exceed 32K (32768) 
bytes. To determine the number of bytes of identification data 
contained ina particular load module, use the following 
formula: 


SIZE = 269 + 16A + 31B + 2C + In + 6) 
where: 


A = the number of compilations or assemblies by a processor 
supporting CSECT identification that produced the object 
code for the module. 


B= the number of preprocessor compiler compilations by a 
processor supporting CSECT identification that produced 
the object code for the module. 


C= the number of control sections in the module with END 
statements that contain identification data. 


I= the number of control sections in the module that contain 
user-supplied data supplied during link-editing by the 
optional IDENTIFY control statement. 


n= the average number of characters in the data specified by 
IDENTIFY control statements. 

Notes: 

1. The size computed by the formula includes space for 


recording up to 19 HMASPZAP modifications. When 75% of 
this space has been used, a new 251-byte record is created 
the next time the module is reprocessed by the linkage 
editor. 


2. To determine the approximate number of records involved, 
divide the computed size of the identification data by 256. 


EXAMPLE: A module contains 100 control sections produced by 20 
unique compilations. Each control section is tdentified during 
link-editing by 8 characters of user data specified by the 
IDENTIFY control statement. The size of the identification 
data is computed as follows: 


A = 20 
I = 100 
n= 8 


269 + 320 + 1400 = 1989 bytes 


If the optional user data specified on the IDENTIFY control 
statements is omitted, the size can be reduced considerably, as 
computed below: 


269 + 320 = 589 bytes 


The maximum number of downward calls made from a segment to 
other segments lower in its path can never exceed 340. To 
compute the maximum number of downward calls allowed, subtract 
12 from the SYSLMOD record size and then divide the difference 
by 12. Examples of maximum downward calls are 84 for a SYSLMOD 
record size of 1024 bytes and 340 for a SYSLMOD record size of 
6144 bytes. 
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Intermediate Data Set 


The intermediate data set (SYSUT1) is used by the linkage 
editor to hold intermediate data records during processing. 
The linkage editor places intermediate data in this data set 
when storage allocated for input data or certain forms of 
out-of-sequence text is exhausted. 


The following direct access devices, if supported by the 


system, 


IBM 
IBM 
IBM 
IBM 
IBM 
IBM 
IBM 
IBM 
IBM 
IBM 
IBM 


2305-1 
2305-2 
2314 
2319 
3330 
3330-11 
3340 
3344 
3350 
3375 
3380 


can be used for this data set: 


Fixed Head Storage Facility 
Fixed Head Storage Facility 
Storage Control Facility 
Disk Storage Facility 

Disk Storage Facility 

Disk Storage Facility 

Disk Storage Facility 

Direct Access Storage Device 
Direct Access Storage Device 
Direct Access Storage Device 


Direct Access Storage Device 
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APPENDIX D. SIZE PARAMETER GUIDELINES 


This appendix gives guidelines for determining appropriate SIZE 
parameter values for a linkage editor job step. 


First—determine Value2 of the SIZE parameter. 


Value2=(6K1/6144/fl|g] Catb) | (cxd) | (cxe) ] 


where: 

a 1s the length of the load module to be built. 

b is 0, if the length of the load module to be built is < 
40K bytes. 
is 4K, if the length of the load module to be built is 2 
40K bytes. 

c is an integer equal to or greater than 2, such that cxd 


or cxXe is S$ 999999 or 9999K bytes (c is the integer that 
represents the number of buffers to be reserved for 
SYSLMOD). 


d is the track capacity of the SYSLMOD device, or 18K 
whichever 1s larger. 


1s the block size of the SYSLMOD data set. 


is the length of the largest text record in load module 
input. 


g is the track capacity of the SYSUT1 device, or 18K 
whichever is larger. 


Selecting the largest of the above parameters provides optimal 
results. 


Second—determine Valuel of the SIZE parameter. 
Valuel = h + j + k 
Valuel must range between h and 9999K or 9999999 


where: 
h = 96K 
j is the excess of Value2 over 6K 
k is the additional storage required to support the 
eeepor eae for SYSLIN, object module libraries, and 


Blocking Factor | K (Bytes) 


5 to l 





40 to 1 


Third—determine the REGION parameter. 
REGION = Equal to or greater than Valuel 
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PART 2. LOADER 


The Loader is a processing program that combines basic editing 
and loading functions of the linkage editor and program fetch 
into one job step. Therefore, the load function is equivalent 
to the link-edit-go function. The loader can be used for 
compile-load and load jobs. 


The loader will load object modules produced by a language 
processor and load modules produced by the linkage editor into 
virtual storage for execution. Optionally, it will search a 
call library CSYSLIB) or a resident link pack area, or both, to 
resolve external references. The loader does not produce load 
modules for program libraries. 


The functional characteristics, compatibility and restrictions, 
performance considerations, and storage considerations of the 
loader are described in the following sections. 


FUNCTIONAL CHARACTERISTICS 


The loader is reenterable and, therefore, can reside in the 
resident link pack area. 


The loader combines the following basic functions of the 
linkage editor and program fetch: 


1. Resolution of external references between program modules. 


2. Optional inelusion of modules from a call library CSYSLIB) 
or from a link pack area, or from both (Figure 64% on page 
161 and Figure 65 on page 162). (Inclusion of modules from 
a call library or the link pack area is performed, if 
requested, when external references remain unresolved after 
processing the primary input to the loader. If both are 
requested, the link pack area is searched first.) 


3. Automatic deletion of duplicate copies of program modules 
(Figure 66 on page 162). (The first copy is loaded and all 
following requests use that copy.) 


4. Relocation of all address constants so that control may be 
passed directly to the assigned entry point in virtual 
storage. 
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were unresolved at the end of input 
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Figure 64. Loader Processing—SYSLIB Resolution 
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Figure 65. Loader Processing—Link Pack Area and SYSLIB Resolution ; ) 
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Figure 66. Loader Processing—Automatic Editing 





162 MVS/370 Linkage Editor and Loader 


c 


Time Sharing Option 


CONPATIBILITY AND RESTRICTIONS 


The loader accepts the same basic input as the linkage editor: 


1. All object modules that can be processed by the linkage 
editor can be input to the loader. 


2. All load modules produced by the linkage editor can be 
input to the loader (except load modules edited with the NE 
option). 


The loader supports the following linkage editor options: MAP, 
LET, NCAL, SIZE, and TERM. All other linkage editor options 
and attributes are not supported, but, if used, they will not 
be considered as errors. A message will be listed on SYSLOUT 
indicating that they are not supported. The supported options 
are specified in the PARM field of the EXEC statement, or with 
the LINK, ATTACH, LOAD, or XCTL macro instruction. In addition 
to the supported linkage editor options, the loader provides 
several other options. All loader options are described under 
WEXEC Statement™ on page 164. 


The loader does not process linkage editor control statements 
(for example, INCLUDE, NAME, OVERLAY, etc.). If they are used, 
they will not be treated as errors, and a message will be 
listed on SYSLOUT indicating that the control statements are 
not supported. 


The loader and the linkage editor are bound by the same input 
conventions. (These conventions are discussed in Part 1 of 
this publication.) In addition, the loader can accept load 
modules in the SYSLIN data set and object modules from a data 
area in virtual storage. 


The loader does not use auxiliary storage space for work areas; 
that is, there is no loader function corresponding to the 
linkage editor's creation of intermediate work data sets or 
output load modules. 


(TSO) 


When the loader is used under TS50, it is invoked by the loader 
prompter, a program that acts as an interface between the user 
and the operating system and the loader. Under 1T50, execution 
of the loader and definition of the data sets used by the 
loader are described to the system through use of the LOADGO 
command that causes the prompter to be executed. Operands of 
the LOADGO command can also be used to specify the loader 
options a job requires. 


Complete procedures for using the LOADGO command to load and 
execute an object module are given in TS0 Command Language 


Reference. 


Processing Object Modules in Virtual Storage 


The loader can act as an interface with a compiler that has the 
ability to construct a data area of one or more object modules 
in virtual storage as an alternative to a data set ona 
secondary storage volume (such as a tape or disk). The 
compiler passes the loader a description of the internal data 
area, which the loader then processes as primary input. This 
internal data area replaces external SYSLIN data set input to 
the loader. 


Instead of placing text records for the object module in the 
internal data area, the compiler can pass pointers to preloaded 
text. The loader can then perform its relocation and linkage 
functions on the preloaded text itself; text is not moved 
during processing. 
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USING THE LOADER 


This section discusses how to prepare an input deck for the 
loader and how to invoke the loader; it also describes the 
output from the loader. 


INPUT FOR THE LOADER 


The tnput deck for the loader must contain job control language 
statements for the loader and, optionally, for the loaded 
program (Figure 6/7). 


//name JOB parameters Coptional ) 
//name EXEC PGM=LOADER, 

PARM=Cparameters) 
//SYSLIN DD parameters 
//SYSLIB DD parameters Coptional) 
//SYSLOUT DD parameters Coptional ) 
//5YSTERM DD parameters Coptional) 
// Coptional DD statements and data 
// required for loaded program) 


Figure 67. Input Deck for the Loader—Basic Format 


Only the EXEC statement and the SYSLIN DD statement are 
required for a loader step. The JOB statement is required if 
the loader is the first step in the job. 


EXEC STATEMENT 
The EXEC statement is used to call the loader and to specify 
options for the loader and the loaded program. The loader is 


called by specifying PGM=HEWLDRGO or PGM=LOADER (see "Invoking 
The Loader™ on page 170). 


PARM Field Format 


Loader and loaded program options are specified in the PARM 
field of the EXEC statement. The PARM field must have the 
following format: 





Note that the loaded program option(s), if any, must be 
separated from the loader option(s) by a slash (7). If there 
are no loader options, the program option must begin with a 
Slash. The entire PARM field may be omitted if there are no 
loader or loaded program options. 


Parameters must be enclosed in single quotation marks when 
special characters (/ and =) are used. 

LOADER OPTIONS 
The loader options are outlined below. Fields that must be 


supplied by the user are underlined; default options are 
underlined in boldface type. 
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CALL INOCALL 
EP=name 

LET [NOLET 
MAP |NOMAP 


NAME=name |NAME=*®*GO 
PRINT |NOPRINT 

RES |NORES 
SIZE=sizelSIZE=300K 
TERM |NOTERM 





CALLINOCALL: Automatically Searching SYSLIB 


EP=name: Specifying 


Explanation: CALL|INOCALL are options specifying whether an 
automatic search of the SYSLIB data set is made when the loader 
1s invoked. 


CALL 
Indicates that the SYSLIB data set will automatically be 
searched when the loader is invoked. 


NOCALL 
Indicates that no automatic search of the SYSLIB data set 
15 to be made. 


Abbreviations: 
NOCALLINCAL 
Default: The default is CALL. 


Restrictions: If the SYSLIB DD statement is not included in 
the input deck, the CALL|NOCALL option is ignored. 


If the NOCALL option is specified, the NORES option is 
automatically set. 


the Program Entry Point 


Explanation: EP=name is a loader option that specifies the 
external name to be assigned as the entry point of the loaded 
program. 


Abbreviations: None. 
Default: None. 


Restrictions: EP=name must be specified if the entry point of 
the loaded program 15 in an input load module. 


For FORTRAN, ALGOL, and PL/I, these entry points must be named 
MAIN, IHIFSAIN, and IHENTRY, respectively, unless changed by 
compiler options. 


LETINOLET: Executing with Severity 2 Errors 


Explanation: LETINOLET are loader options specifying whether 
the loader should try to execute the object program if a 
severity 2 error condition is found. A severity 2 error 
condition is one that could make execution of the loaded 
program tmpossible. 


LET 
Indicates that the loader will attempt to execute the 
program even if a severity 2 error is found. 
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MAP | NOMAP: 


NAME=name: 


PRINT [NOPRINT: 


RES |NORES: 


166 





NOLET 
Indicates that the loader will not attempt to execute the 
program if a severity 2 error is found. 

Abbreviations: None. 


Default: The default is NOLET. 


Printing a Program Map 


Explanation: MAP|NOMAP are loader options specifying whether 
to produce a map of the loaded program that lists external 
names and their absolute storage addresses on the SYSLOUT data 
set. The module map is described in “Loader Output" on page 
174. 


MAP 
Indicates that a program map will be printed. 


NOMAP 
Indicates that a program map will not be printed. 


Abbreviations: None. 
Default: The default is NOMAP. 


Restrictions: If the SYSLOUT DD statement is not used in the 
input deck, the MAP|NOMAP option is ignored. 


Identifying the Loaded Program 


Explanation: NAME=name is a loader option specifying the name 
to be used to identify the loaded program to the system. 


Abbreviations: None. 


Default: If this option is not used, the loaded program will 
be named **GO. 


Printing Messages on SYSLOUT 


Explanation: PRINT|NOPRINT are loader options specifying that 
informational and diagnostic messages are to be produced on the 
SYSLOUT data set. 


PRINT 
Indicates that messages are printed in SYSLOUT. 


NOPRINT 
Indicates that no messages are printed in SYSLOUT. 


Abbreviations: None. 
Default: The default is PRINT. 


Restrictions: If NOPRINT is specified, the SYSLOUT data set is 
not opened. 


Automatically Searching the Link Pack Area Queue 


Explanation: RES|NORES are loader options specifying whether 
an automatic search of the link pack area queue is to be made 
after processing the primary input CSYSLIN) and before 
searching the SYSLIB data set. 


RES 
Indicates that an automatic search of the link pack area 
queue 1s to be made. 
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NORES 
Indicates that no automatic search of the link pack area 
queue 1s to be made. 


Abbreviations: None. 
Default: The default is RES. 


Restrictions: When the RES option is specified, the CALL 
option is also automatically set. 


SIZE=size: Specifying Virtual Storage 


Explanation: SIZE=size is a loader option specifying the 
amount of dynamic virtual storage, in bytes, that can be used 
by the loader. See "Appendix F. Loader Return Codes" on page 
178 for more information on size. 


Abbreviations: None. 


Default: If this option is not specified, the size defaults to 
300K bytes. 


TERMINOTERM: Sending Messages to SYSTERM 


Explanation: TERM|JNOTERM are loader options specifying whether 
to send numbered diagnostic messages to the SYSTERM data set. 
Although TERMINOTERM is intended to be used when operating 
under the Time Sharing Option (TSO), the SYSTERM data set can 
be used to replace or supplement the SYSLOUT data set at any 
time. 


TERM 
Indicates that numbered diagnostic messages are sent to 
the SYSTERM data set. 


NOTERM 
Indicates that no messages are to be sent to SYSTERM. 


Abbreviations: None. 
Default: The default is NOTERM. 
Restrictions: If the SYSTERM DD statement is not included in 
the input deck, the TERM option is ignored. 
EXEC STATEMENT EXAMPLE 
The following are examples of the EXEC statement. In these 


examples, X and Y are parameters required by the loaded 
program. 


//LOAD PGM=LOADER 
PGM=HEWLDRGO, 
PARM="MAP,EP=FIRST/X,Y' 
PGM=LOADER,PARM='/7X,Y' 


PGM=LOADER,PARM=NOPRINT 

PGM=LOADER,PARM=C(CMAP,LET) 
//LOAD PGM=LOADER, 

PARM="*NAME=NEWPROG, TERM,NOPRINT ' 
4/ 





For further details in coding the EXEC statement, refer to the 
publication JCL. 
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DD STATEMENTS 
The loader uses four DD statements, named SYSLIN, SYSLIB, im 
SYSLOUT, and SYSTERM. The SYSLIN DD statement must be used in 
every loader job. The others are optional. 


The following considerations apply to the DCB parameter of 
SYSLIN, SYSLIB, and SYSLOUT. 


° For better performance, BLKSIZE and BUFNO can be specified. 
° If BUFNO is omitted, BUFNO=2 its assumed. 


® Any value given to BUFNO is assumed for NCP (number of 
channel programs). 


e If RECFM=U is specified, BUFNO=2 is assumed, and BLKSIZE 
and LRECL are ignored. 


e RECFM=V is not accepted. 
e RECFM=FBSA is always assumed for SYSLOUT. 


° If RECFM is omitted, RECFM=F is assumed for SYSLIN and 
SYSLIB. 


e If BLKSIZE is omitted, the value given to LRECL is assumed. 

e LRECL=121 is assumed for SYSLOUT unless the loader is 
operating under the Time Sharing Option (TS0), when 
LRECL=81 is assumed. 


° If LRECL is omitted, LRECL=80 is assumed for SYSLIN and 


SYSLIB. 
e If OPTCD=C is used to specify chained scheduling, and if : 
the necessary data management routines are not resident, an 


additional 2K bytes (2048 bytes) of virtual storage is 
needed in the user's region. 


Note: The SYSTERM data set will always consist of unblocked 
8i-character records with BUFNO=2 and RECFM=FSA. Because these 
values are fixed, the DCB parameter need not be used. 


In addition to the DD statements used by the loader, any DD 
statements and data required by the loaded program must be 
included in the input deck. 


SYSLIN DD Statement 


The SYSLIN DD statement defines the input data for the loader. 
This input can be either object modules produced by a language 
translator, or load modules produced by the linkage editor, or 
both. The data sets defined by the SYSLIN DD statement can be 
either sequential data sets or members of a partitioned data 
set, or both. The DSNAME parameter for a partitioned data set 
must indicate the member name, that is, 


DSNAME=dsname(membername). 


Concatenation can be used to include more than one module in 
SYSLIN. 


The following are examples of the SYSLIN DD statement. The 
first example defines a member of a previously cataloged 
partitioned data set: 


//SYSLIN DD DSNAME=OUTPUT.FORTCMODI2), , 
47 DISP=OLD,DCB=BLKSIZE=3200 ) 


The second example defines a sequential data set on magnetic 
tape: 
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//SYSLIN DD DSNAME=PROG15,UNIT=3400-6,DISP=COLD, 
17 KEEP),VOLUME=CPRIVATE,RETAIN, 
// SER=MCS167) 


The third example defines a data set that was the output of a 
previous step in the same job: 


//SYSLIN DD DSNAME=*.COBOL.SYSLIN,DISP=COLD, 
// DELETE) 


The fourth example shows the concatenation of three data sets. 
The first two data sets are members of different partitioned 
data sets; the first is an object module, and the second is a 
load module. The third data set is in the input stream 
following a SYSLIN DD statement (see "Loaded Program Data™ on 


page 170). 

//SYSLIN DD DSNAME=PGMLIB.SET1ICRFS1),DISP=OLD, 
// DCB=(BLKSIZE=3200,RECFM=FB) 

// DD DSNAME=PGMLIB.SET2CABC5),DISP=OLD, 
17 DCB=RECFM=U 

/7/ DD DDNAME=SYSIN 


SYSLIB DD Statement 


The SYSLIB data set contains IBM-supplied or user-written 
library routines to be included in the loaded program. The 
data set is searched when unresolved references remain after 
processing SYSLIN and optionally searching the link pack area. 


The SYSLIB data set is used to resolve an external reference 
when the following conditions exist: the external reference 
must be (1) a member name or an alias of a module in the data 
set, and (2) defined as an external name in the external symbol 
dictionary of the module with that name. If the unresolved 
external reference is a member name or an alias in the library, 
but 1s not an external name in that member, the member is 
processed but the external reference remains unresolved unless 
subsequently defined. 


The data set defined by the SYSLIB DD statement must be a 
partitioned data set that contains either object modules or 
load modules, but not both. Concatenation may be used to 
include more partitioned data sets in SYSLIB. All concatenated 
data sets must contain the same type of modules (object or 
load). 


The following are examples of the SYSLIB DD statement. The 
first example defines a cataloged partitioned data set that can 
be shared by other steps: 


//SYSLIB DD DSNAME=SYS1.ALGLIB,DISP=SHR 
The second example shows the concatenation of two data sets: 


//SYSLIB DD DSNAME=SYS1.PLILIB,DISP=SHR 
// DD DSNAME=LIBMOD.MATH, DISP=OLD 


SYSLOUT DD Statement 


The SYSLOUT DD statement is used for error and warning messages 
and for an optional map of external references (see "Loader 
Output™ on page 174). The data set defined by this DD 
statement must be a sequential data set. The DCB parameter can 
be used to specify the blocking factor (BLKSIZE) of this data 
set. For better performance, the number of buffers (BUFNO) to 
be allocated to SYSLOUT can also be specified. 


The following are examples of the SYSLOUT DD statement. The 
first example specifies the system output unit: 


4/SYSLOUT DD SYSOUT=A 
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The second example defines a sequential data set on a 3800 ) 


printer: 
//SYSLOUT DD UNIT=3800,DCB=(BLKSIZE=121, 
// BUFNO=4) 


SYSTERM DD Statement 


The SYSTERM DD statement defines a data set that is used for 
numbered diagnostic messages only. When the loader is being 
used under the Time Sharing Option (TSO) of the operating 
system, the SYSTERM DD statement defines the terminal output 
data set. However, SYSTERM can also be used at any time to 
replace or supplement the SYSLOUT data set. Because the 
SYSTERM data set 1s not opened unless the loader must issue a 
diagnostic message, using SYSTERM instead of SYSLOUT can reduce 
loader processing time. 


When the SYSTERM data set replaces the SYSLOUT data set, the 
numbered messages in the SYSTERM data set are the only 
diagnostic output; when SYSTERM supplements the SYSLOUT data 
set, the numbered messages appear tn both data sets, and 
optional diagnostic and informational output, such as a list of 
options or a module map, can be obtained on SYSLOUT. 


The DCB parameters for SYSTERM are fixed and need not be 
specified. The SYSTERM data set always consists of unblocked 
8i-character records with BUFNO=2 and RECFM=FSA. 


The following example shows the SYSTERM DD statement when used 
to specify the system output unit: 


J/SYSTERM DD SYSOUT=A 


| 
LOADED PROGRAM DATA 2 


Loaded program data and loader data can both be specified in 
the input reader. Loaded program data can be defined by a DD 
statement following the loader data. 


Figure 68 shows the loading of a previously compiled FORTRAN 
problem program. The program to be loaded (loader data) 
follows the SYSLIN DD statement. The loaded program data 
follows the FTO5F001 DD statement. 


//LOAD JOB MSGLEVEL=1 

/7LDR EXEC PGM=LOADER, PARM=MAP 

S/SYSLIB DD DSNAME=SYS1.FORTLIB,DISP=SHR 
//SYSLOUT DD SYSOUT=A 

//FTO6F001 DD SYSOUT=A 

//SYSLIN DD X 


(Loader data) 


7% 
//FTO5SFOOL DD ¥ 

(Loaded program data) 
/¥ 


Figure 68. Loader and Loaded Program Data Input Stream 





INVOKING THE LOADER 2 


The loader can be referred to by either its program name, 
HEWLDRGO, or its alias, LOADER. The loader can be tnvoked 
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through the EXEC statement, as described in “Input for the 
Loader™ on page 164%, or through one of the following macro 
instructions. 


[symbol] LINK EP=loadernames 
PaARAM=Coptionlistl,ddname listl), 
VL= 


[symbol] ATTACH EP=loadername, 
coca caestontisttddnams list]), 
VL= 


[symbol ] LOAD EP=loadername 


[symbol] XCTL EP=loadername 





EP=loadername 
specifies the symbolic name of the loader. The entry point 
at which execution is to begin 1s determined by the control 
program from the library directory entry. 


PARAM=[(optionlistl,ddname list]) 
specifies, as a sublist, address parameters to be passed to 
the loader. The first fullword in the address parameter 
list contains the address of the option list for the loader 
and/or loaded program. The second fullword contains the 
address of the ddname list. If standard ddnames are to be 
used, ddname list may be omitted. 


optionlist 
specifies the address of a variable-length list 


containing the loader and loaded program options. 
This address must be written even though no real list 
is provided; for example, when the optionlist points 
to a halfword of zero. 


The option list must begin on a halfword boundary. 

The two high-order bytes contain a count of the number 
of bytes in the remainder of the list. If no options 
are specified, the count must be zero. 


The option list is free form, with the loader and 
loaded program options separated by a slash (/), and 
with each option separated by a comma. No blanks or 
zeros should appear in the list. 


ddname list 
specifies the address of a variable-length list 
containing alternative ddnames for the data sets used 
during loader processing. If the standard ddnames are 
used, this operand may be omitted. 


The format of the ddname list is identical to the 


format of the ddname list for invoking the linkage 
editor; the 8-byte entries in the list are as follows: 


Using the Loader 1/71 











[entry | alternate nana Fort 
ee co 
[2 [vet spntieatie 
Ts [not splieabie 
ra 
cae 








specifies that the sign bit is to be set to 1 in the last 
fullword of the address parameter list. 


Figure 69 shows an Assembler language program that uses the LINK 
macro instruction to refer to the loader. 


SAVE (14,12) Initialize save 
: registers and point 
to new save area 


LA 13,SAVEAREA ) 


LINK EP=LOADER, PARAM=(PARM),VL=1 


L 13,4013) 
RETURN €14,12),T 


DS OH 
PARM DC AL2CLENGTH) Length of options 
OPTIONS DC C*NOPRINT,CALL/X,Y,2Z' loader and loaded 
LENGTH EQU *-OPTIONS program options 
SAVEAREA DS 18F Save area 

END 


Figure 69. Using the LINK Macro Instruction to Refer to the 
Loader 


If desired, the loader may be used to process a program but not 
execute it. To invoke just the portion of the loader that 
processes input data, specify either the name HEWLOAD or the 
name HEWLOADR with a LOAD and CALL macro instruction. 


HEWLOAD loads and identifies the program. HEWLOAD returns the 
address of an 8-character name in register 1. This name can be 
used with an ATTACH, LINK, LOAD, or XCTL macro instruction to 

invoke the loaded program. A user program that 1s going to 

attach a loaded program should avoid specifying SZERO=NO in its 

ATTACH macro. If SZERO=NO must be specified, the user program 
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FREE 


PARM1 
OPTIONS1 
LENGTH1 


PARM2 
OPTIONS2 
LENGTH2 
SAVEAREA 


Figure 70. 


should issue a LOAD for the loaded program before parforming the 
ATTACH and a DELETE for the loaded program after the ATTACH. 


HEWLOADR loads the program but will not identify it. HEWLOADR 
returns the entry point of the loaded program in register 0. 
Register 1 points to two fullwords: the first points to the 
begining of storage occupied by the loaded program; the second 
contains the size of the loaded program. This location and size 
can then be used in a FREEMAIN macro instruction to free the 
erereee occupied by the loaded program when it is no longer 
needed. 


Figure 70 shows an Assembler language program that uses the LOAD 
and CALL macro instructions to refer to HEWLOADR. Figure 71 on 

page 174 shows an Assembler language program that uses the LOAD 

and CALL macro instructions to refer to HEWLOAD. 


SAVE €14,12),T Initialize save registers 
? and point to new save area 
ST 13,SAVEAREA+4 
LA 13,SAVEAREA 
LOAD EP=HEWLOADR Load the loader 
LR 15,0 Get its entry point address 
CALL €15),CPARM1),VL=1 Invoke the loader 
LR 7915 save return code 
LR 5,0 Save entry tn loaded program 
LR 6,1 Save »c =* to list containing 
Start address and length 
DELETE EP=HEWLOADR Delete loader 
CH 7,=H'4? Verify successful loading 
BH FREE Negative branch 
LR 15,5 Loading successful—get entry 
Potnt address for CALL 
CALL €15),CPARM2),VL=1 Invoke program 
L 0,4(6) Get length into register 0 
L 1,0¢6) Get start address 
FREEMAIN R,LV=(€0),A=C1) Delete loaded program 
13,4¢13) 
RETURN €14,12),T 
DS OH 
DC AL2CLENGTH1) Length of loader options 
DC C*NOPRINT,CALL’® Loader options 
EQU *-OPTIONSI 
DS OH 
DC AL2CLENGTH2) Length of loaded program options 
DC C Xs YoZ" Loaded program options 
EQU *-OPTIONS2 
DS 18F Save area 
END 


Using the LOAD and CALL Macro Instructions to Refer to HEWLOADR CLoading 
Without Identification) 
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SAVE €14,12),T 
ST 13,SAVEAREAt+4 
LA 13,SAVEAREA 
LOAD EP=HEWLOAD 
LR 15,0 
CALL €15),CPARM1),VL=1 
LR 7,15 
MVC PGMNAM(8),0(€1) 
DELETE EP=HEWLOAD 
CH 7,=H'4' 
BH ERROR 
LINK 
ERROR L 13,4(13) 
RETURN €14,12),T 
DS 0H 
PARM1 DC AL2CLENGTH1) 
OPTIONS1 DC C'MAP* 
LENGTH1 EQU *-OPTIONS1 
DS OH 
PARM2 DC AL2CLENGTH2) 
OPTIONS2 DC C'X,Y,2' 
LENGTH2 EQU ¥-OPTIONS2 
SAVEAREA DS 18F 
PGMNAM DS 2F 
END 


Initialize save registers and 
point to new save area 


Load the loader 

Get its entry point address 
Invoke the loader 

Save the return code 

Save program name 

Delete the loader 

Verify successful loading 
Negative branch 


EPLOC=PGMNAM, PARM=CPARM2),VL=1 


Loading successful, 
invoke program 


Length of loader options 
Loader options 


Length of loaded program options 
Loaded program options 


Save area 
Program name 


Figure 71. Using the LOAD and CALL Macro Instructions to Refer to HEWLOAD (Loading 


With Identification) 


For further information on the use of these macro instructions, 
see System Programming Library: Supervisor Services and Macro 


Instructions. 


LOADER OUTPUT 


Loader output consists of a collection of diagnostics and error 
messages, and of an optional storage map of the loaded program. 
This output is produced in the data set defined by the SYSLOUT 


DD and SYSTERM DD statements. 


output is produced. 


If these are omitted, no loader 


SYSLOUT output includes a loader heading, and the list of 
options and defaults requested through the PARM field of the 


EXEC statement. 


necessarily the size requested in the PARM field. 
messages are written when the errors are detected. 
processing is complete, 


The SIZE stated is the size obtained, and not 


Error 
After 
an explanation of the error is written. 


Loader error messages are similar to those of the linkage editor 
and are listed in Linkage Editor and Loader Messages. 


SYSTERM output includes only numbered warning and error 


messages. 
detected. 
error is written. 
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These messages are written when the errors are 
After processing is complete, an explanation of each 


J 





OPTIONS 


NAME 


SAMPL2B 
SYSIN 
IHEDIA 
IHEVPA 
IHEVPCA 
IHEDNC 
IHEDMA 
IHEVFAA 
ITHEIOB 
IHESARC 
IHEBEGA 
IHEERRA 
IHEITAZ 
IHEDCNB 
IHEVTB 


IHEQINV 
SYSIN 

IHEQLW3 
IHEQFYD 
IHEQEVT 
IHEQSFC 


IEW1001 
IEW1001 
IEW1001 
IEw1001 
IEw1001 
IEW1001 
IEw1001 
IEwW1001 
IEW1001 
IEW1001 
IEw1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEw1001 


TOTAL 
ENTRY 


TEW1001 


Figure 72. 





includes the name and absolute address of each 
control section and entry point defined in the loaded program. 
Each map entry marked with an asterisk (*) comes from the data 
set specified on the SYSLIB DD statement. Two asterisks (x) 
indicate the entry was found in the link pack area; three 
asterisks (***) indicate the entry comes from text that was 
preloaded by a compiler. The TYPE column indicates what each 
entry on the map is used for: SD=control section, LR=label 
reference, and PR=pseudo register. 


The storage map 


input to the loader is processed, so 
in which the input 


is written as the 
in the same sequence 


The map 
all map entries appear 
ESD items are defined. 
loaded program are also included. For PL/I programs, a list is 
written showing pseudo registers with their addresses assigned 
relative to zero. Figure 72 shows an example of a module map. 
The loader issues an informational message when the loaded 
program terminates abnormally. 


USED-PRINT,MAP,NOLET,CALL,NORES,SIZE#424176 


TYPE 


SD 
SD 
SD 
SD 
LR 
SD 
SD 
LR 
SD 
LR 
LR 
LR 
LR 
LR 
SD 


e* #*# @#@ © @#@ #@# @ & &@ & 8 H & 


PR 
PR 
PR 
PR 
PR 
PR 


IHEUPBA 
THEUPAA 
IHETERA 
THEM9 1C 
IHEM9 1B 
IHEM91A 
IHEDDOD 
IHEVPFA 
IHEVPDA 
IHEDBNA 
ITHEVSFA 
IHEVSBA 
THEVCAA 
IHEVSAA 
IHEDNBA 
IHEUPBB 
IHEUPAB 
IHEVSEB 


LENGTH 
ADDRESS 


WARNING 


ADDR 


161E0O 
17D48 
183C0 
18870 
1869F8 
18CB8 
19010 
19160 
19468 
1A9CB 
1AE28 
1AE86 
1BR1E 
1B862 
1BCFO 


00 
14 
28 
3C 
58 
70 


5068 
17D00 


- UNRESOLVED EXTERNAL REFERENCE 


NAME 


SAMPL2BA 
IHEVOC 
IHEDIAA 
LHEVPAA 
IHEVFE 
IHEDNCA 
IHEDMAA 
IHEVPB 
IHEIOBA 
IHESADD 
IHEERR 
IHEERRE 
[HEI TAX 
IHEIOD 
IHEVTBA 


LHEGERR 
LHEQLSA 
THEQLW4 
[HEQCFL 
THEQSLA 


TYPE ADDR NAME TYPE ADDR NAME TYPE ADDR NAMF TYPE ADDR 

SD 16EC8  IHEMAIN SD 17°F8 THENTRY SD 17D0Q0 THESPRT SD 17D10 
SD 17080 THEVOCA * LR 17080 THEVQOB * SD 17FD8 ITHEVQOBA* 1.17 17 FD8 
LR 183C0  IHEDIAB * LR 18 302 IHEVPE * SD 18608 IHEVPEA® LP TRHOB 
LR 1H870 THEVFC * SD 1B89DG) IHEVFCA * LR 189DQ0, JTHEVPC * SD 169FB 
sD 18BE8 IHEVFEA * LR 18BE8 THEVSC * Sh 1TB8COH THEVSCA* LR 18C08 
LR 18CB8 IHEDOA * = SD 18F30 THEDOAA * LR THF 30) THEDOAB*® LR 18F 32 
LR 19010 THEVFD * sD 19108 IHEVFDA * LR 19108 IHEVFA * SD 19160 
sD 19248 JHEVPBA * _ LR 19248 JHEXIS * SD 193FU0 THEXISO* LR 14 3F0 
LR 19488 YTHEIOBB * LR 19490 THEITOBC * LR 19498% THEIOBD* LR 194At) 
LR JA9DE IHESAFF * LR TAAI& JTHEPRT *® SD 1AB70 TLHEPRTA®* LR 1AB70 
SD TAE64 IHEERRD * ~ LR TAE6u JHEERR« * LR TAE72 IHEERRB* LR 1AE 7¢ 
LR 1B4E2 IHEIOF * = SD 1B580) JHETOFB * LR 1TB5S8O)  THEIOFA®*® LR 1B582 
LR 1B82A IHEITAA * LR 1Bs 3F IHEDCN * SD 1B860 THEDCNA® LR TB8tH0 
SD 1BA5SO THEIODG * LR 1BASO IHETODP * LR TBAS2 IHEIODT* LR TBB4A 
LR 1BCFQO IHEVQA * = SD 1BD78 IHEVQAA * LR 1BD78 

PR 4 SAMPL2BB PR 4 = SAMPL 2 PR C I[HEQSPR- PR 10 
PR 18 THEQLWO PR 1 THEVLW1 PR 20 THEQLW2 PR 24a 
PR et IHEQLWE PR 300 THEQLUA PR 34° IHEQOVDA- FR 38 
PR 40 IHEQFOP PR 44H LHEQVALx PR a [HEQXLV PR 50 
PR ot) ~=THEQSAR PR 64  IHEQLWF PR 68 THEORT( PR H( 


(NOCALL SPECIFIED! 


Module Map Format Example 


Using the Loader 


The total size and storage extent of the 
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Figure 73 shows an input deck for a load job. A previously 
assembled program, MASTER, is to be loaded. The SYSLOUT, 
SYSLIB, and SYSTERM DD statements are not used. 


//LOAD JOB MSGLEVEL=1 
// EXEC PGM=LOADER 
//SYSLIN DD DSNAME=MASTER, DISP=OLD 


(DD statements and data required for execution of MASTER) 


7% 


Figure 73. Input Deck for a Load Job 


Figure 74 shows an input deck for a compile-load job. The OS/VS 
COBOL CIKFCBL0O0) compiler is used for the compile step. The 
loaded program requires the SYSOUT, TAXRATE, and SYSIN DD 
statements. 


//530B JOB 22,MCS,MSGLEVEL=1 
//COBOL EXEC PGM=IKFCBL00,PARM=DMAP,REGION=256K,RD=R 
4/SYSPRINT DD SYSOUT=A 
7/SYSPUNCH DD SYSOUT=B 
//5YSUT1 DD UNIT=SYSDA,SPACE=C(TRK,(€100,10)) 
//SYSUT2 DD UNIT=SYSDA,SPACE=C(TRK,(100,10)) 
//5YSUT3 DD UNIT=SYSDA,SPACE=CTRK,(100,10)) 
//SYSUT4 DD UNIT=SYSDA,SPACE=CTRK,(100,10)) 
//SYSLIN DD DSNAME=&&_LOADSET,DISP=(MOD,PASS), 
// UNIT=SYSSQ,SPACE=C(TRK,(30,10)) 
//SYSIN DD x 

(source program) 
//LOAD EXEC PGM=LOADER,PARM='"MAP,LET’,COND=C(5,LT, 
// COBOL) 
4/SYSLIN DD DSNAME=%.COBOL.SYSLIN,DISP=COLD, 
// DELETE) 
//S5YSLOUT DD SYSOUT=A 
J/SYSLIB DD DSNAME=SYS1.COBLIB,DISP=SHR 
//SYSOUT DD SYSOUT=A 
//TAXRATE DD DSNAME=TAXRATE,DISP=OLD 
7/SYSIN DD * 


(Data for Loaded Program) 


7¥ 


Figure 74. Input Deck for a Compile-Load Job 


Figure 75 on page 177 shows the compilation and loading of three 
modules. In the first three steps, the OV/VS FORTRAN CFORTYS) 
compiler is used to compile a main program, MAIN, and two 
subprograms, SUB1 and SUB2Z. Each of the object modules is 
placed in a sequential data set by the compiler and passed to 
the loader job step. In addition to the FORTRAN library, a 
private library, MYLIB, is used to resolve external references. 
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In the loader job step, MYLIB is concatenated with the SYSLIB DD 
statement. SUB1 and SUB2 are included in the program to be 
loaded by concatenating them with the SYSLIN DD statement. The 
SYSTERM statement is used to define the diagnostic output data 
set. The loaded program requires the FTOLF001 and FTiOF001 DD 
statements for execution, and it does not require data tn the 
input stream. 


47 JOBX JOB 
//STEP1 EXEC PGM=FORTVS,PARM="NAME=MAIN,LOAD' 


7/SYSLIN DD DSNAME=&&GOFILE, DISP=(€,PASS),UNIT=SYSSQ 
7/35YSIN DD ss 


€Source module for MAIN) 


7% 
//STEP2 EXEC PGM=FORTVS,PARM="NAME=SUB1,LOAD‘ 


//SYSLIN DD DSNAME=&&SUBPROG1,DISP=(€,PASS),UNIT=SYSS@ 
//SYSIN DD % 


(Source module for SUB1) 


7% 
//STEP3S EXEC PGM=FORTVS,PARM="NAME=SUB2,LOAD' 


//SYSLIN DD DSNAME-&&SUBPROG2, DISP=(,PASS),UNIT=SYSS@ 
//SYSIN DD % 


(Source module for SUB2) 


/¥* 

7/STEP4 EXEC PGM=LOADER 

7/SYSTERM ODD SYSOUT=A 

4/SYSLIB DD DSNAME=SY51.FORTLIB,DISP=OLD 


// DD DSNAME=MYLIB,DISP=OLD 

7/SYSLIN DD DSNAME=*.STEP1.SYSLIN, DISP=OLD 
// DD DSNAME=*%.STEP2.SYSLIN,DISP=OLD 
// DD DSNAME=% .STEP3.SYSLIN,DISP=OLD 


//FTO1FO001 DD DSNAME=PARAMS, DISP=OLD 
//FT10F001 DD SYSOUT=A 
7¥® 


Figure 75. Input Deck for Compilation and Loading of the Three 
Modules 
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APPENDIX F. LOADER RETURN CODES 


The return code of a loader step is determined by the return 
codes resulting from loader processing and from loaded program 
processing. 


The return code indicates whether errors occurred during the 
execution of the loader or of the loaded program. The return 
code can be tested through the COND parameter of the JOB 
statement specified for this job and/or the COND parameter of 
the EXEC statement specified in any succeeding job step. (For 
details, see the publication JCL). Figure 76 shows the return 
codes. 


Code 
Returned 
to Caller Conclusion or Meaning 


Program loaded successfully, 
and execution of the loaded 
program was successful. 


The loader found a condition 
that may cause an error during 
execution, but no error 
occurred during execution of 
the loaded program. 


8CLET) The loader found a condition 
that may cause an error during 
execution, but no error 
occurred during execution of 
the loaded program. 


Program loaded successfully, 
and an error occurred during 
execution of the loaded 
program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


Program loaded successfully, 
and an error occurred during 
execution of the loaded 
program. 





Figure 76 (Part 1 of 2). Return Codes 


1 Error diagnostics (SYSOUT and/or SYSTERM data set) for the 
loader will show the severity of errors found by the loader. 
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Code 
Returned 
to Caller 


8CLET) 


= 


a 
_ 
wei 
aa 


Figure 76 (Part 2 of 2). 





Conclusion or Meaning 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader found a condition 
that could make execution 
impossible. The loaded 
program was not executed. 


Program loaded successfully, 
and an error occurred during 
execution of the loaded 
program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader could not load the 
program successfully; 
execution impossible. 


Program loaded successfully, 
and the loaded program found a 
terminating error. 


The loader found a condition 
that may cause an error during 
execution, anda terminating 
error was found during 
execution of the loaded 
program. 


The loader found a condition 
that may cause an error during 
execution, anda terminating 
error was found during 
execution of the loaded 
program. 


The loader could not load 
program; execution impossible. 


Return Codes 
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APPENDIX G. STORAGE CONSIDERATIONS 


Consideration 


J 
The loader requires virtual storage space for the following 
items: 


e Loader code 

° Data management access methods 

° Buffers and tables used by the loader (dynamic storage) 
e Loaded program (dynamic storage) 


Region size includes all four of the above items; the SIZE 
option refers to the last two items. 


For the SIZE option, the minimum required virtual storage is 4K 
bytes plus the size of the loaded program. This minimum 
requirement grows to accommodate the extra table entries needed 
by the program being loaded. For example, FORTRAN requires at 
least 3K bytes plus 4K bytes plus the size of the loaded 
program, and PL/I needs at least &K bytes plus 4K bytes plus the 
size of the loaded program. Buffer number (BUFNO) and block 
size (BLKSIZE) could also increase this minimum size. Figure 77 
shows the appropriate storage requirements in bytes. 


The maximum virtual storage that can be used is whatever virtual 
storage is available up to 8&192K bytes. 


All or part of the storage required 1s obtained from user 
storage. If the access methods are made resident at IPL time, 


they are allocated in system storage. However, 6K bytes is 
always reserved for system uSe. 

| 
The loader code could also be made resident in the link pack 2 


area. If so, it requires the following space: HEWLDRGO, the 
control/interface module (alias LOADER), approximately 700 
bytes; HEWLOADR, the loader processing portion, approximately 
13 664 bytes. 


The size of the loaded program is the same as if the program had 
been processed by the linkage editor and program fetch. 


The loader does not use auxiliary storage space for work areas. 


Approximate 

Virtual Storage 

Requirements 

(in Bytes) Comments 


Data Management 


Object Module Buffers BUFNOXCBLKSIZE + 24) Concatenation of 


and DECBs 


different BLKSIZE and 
BUFNO must be 
considered. (Minimum 
BUFNO=2) 


Load Module Buffer and 


DECBs 





Figure 77 (Part 1 of 2). Virtual Storage Requirements } 
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Consideration 


Approximate 
Virtual Storage 
Requirements 
(in Bytes) 


SYSTERM DCB Buffers and 312 
DECBs 


SYSLOUT Buffers and 
DECBs 


Size of program being 
loaded 


BUFNOXCBLKSIZE + 24) 


Program size 


Allocated if TERM 
option is specified 


Buffer size rounded up 
to integral number of 
double words. (Minimum 
BUFNO=2) 


Program size is 
restricted only by 
available virtual 
storage, up to 8 
megabytes 


Each external relocation 
dictionary entry 


Largest ESD number 


Fixed Loader Table Size 


4n (Cn is the largest 
number of ESDs in any 
input module) 


Condensed Symbol Table 


System Requirements 


Figure 77 (Part 2 of 2). 


12n Cn is the total 
number of control 
sections and common 
areas in the loaded 
program) 


Virtual Storage Requirements 


Appendix G. 


Allocated in 
increments of 32 
entries 


Subtract 88 
1s specified 


if NOPRINT 


Built only if TS0 is 
operating and space 15s 
available 





Storage Considerations 
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APPENDIX H. LOAD MODULE FORMAT 


The format of a load module built by the linkage editor is shown 
in Figure 78. 


In writing the output load module to the SYSLMOD data set, the 
linkage editor does not use the track overflow feature. When 
moving or copying load modules, the track overflow feature must 
not be used on the target data set, as errors may occur in 
fetching the load modules for execution. 


TTR-P2, if TEST option and SYM records present 


TTR-P2, if no TEST option 
TTR-T3, if OVLY option used TTR-TS3, if no OVLY option 


TTR-N/S!, if SCTR 
yortion 


| SYM | | CESD | | IDR | | CTL | | SEGTAB | | SCTR | | CTL | | Ist TXT | | ENTAB | (continued) 


t Present if TEST Nites if OVLY en if SCTR A Present if OVLY option 
option and SYM option and more option is used used and more than | 
records present than ] segment segment 


TTR-N/S!, if OVLY option 
and more than | segment 


| RLD | |_CIRL,RLD,., CTL, RLD, TXT, ENTAB | L RLD | | CTL | | TXT | | TTR | 


, Carries EQS if Carries EOM f Carries EOM f Present if OVLY option 
following ENTAB if this is RLD if no RLDs and more than | segment 
for Last TXT for Last TXT 


ITTR-N/S: TTR of the note list or scatter/translation table. Used for 
modules in scatter load format or overlay structure only. 


2TTR-P: TTR of the first block of the named member (load module). 
3TTR-T: TTR of the first block of text. 


Figure 78. Load Module Format 
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GLOSSARY 


This glossary includes definitions 
developed by the American National 
Standards Institute CANSI). This 


material 1s reproduced from the American 


National Dictionary for Information 
Processing, copyright 1977 by the 
Computer and Business Equipment 
Manufacturers Association, copies of 
which may be purchased from the American 
National Standards Institute, 1430 
Broadway, New York, New York 10018. 

ANSI definitions are preceded by an 
asterisk(X). 


Xaddress. An identification, as 
represented by a name, label, or number, 
for a register, location in storage, or 
any other data source or destination 
such as the location of a station in a 
communication network; any part of an 
instruction that specifies the location 
of an operand for the instruction. 


address constant. A value, or an 
expression representing a value, used in 
the calculation of storage addresses; 
can be used for branching or retrieving 
data. 


addressing mode (AMODE). The attribute 
of an entry point in which control is 
received. 


address translation. The process of 
changing the address of a data item or 
an instruction from its virtual address 
to the real storage address of the 
location where it will reside. See also 
dynamic address translation. 


alias name. An alternate name or entry 
point for a load module that is also 
entered in the output module library 
directory entry along with the member 
name. 


automatic call library mechanism. The 
process whereby control sections are 
processed by the linkage editor or 
loader to resolve external references to 
members of partitioned data sets not 
resolved by primary input processing. 


auxiliary storage. Data storage other 
than virtual storage; for example, 
storage on magnetic tape or 
direct-access devices. 


common area. A control section used to 
reserve a virtual storage area that can 
be referred to by other modules; may be 
either named or unnamed (blank). 


common segment. A segment upon which 
two exclusive segments are dependent. 


composite external symbol dictionary 
(CESD). Control information associated 


with a load module that identifies the 
external symbols in the module. 


control section. That part of a program 
Cinstructions and data) specified by the 
programmer to be a relocatable unit, all 
elements of which are to be loaded into 
adjoining storage locations for 
execution. Abbreviated CSECT. 


control section name. 
of a control section. 


The symbolic name 


demand paging. Transfer of a page from 
external page storage to real storage at 
the time it is needed for execution. 


downward reference. A reference made 
from a segment to another segment lower 
in the same path; that is, farther from 
the root segment. 


dynamic address translation (DAT). (1) 
The change of a virtual storage address 
to a real storage address during 
execution of an instruction. See also 
address translation. (2) A hardware 
feature that performs the translation. 


entry name. <A name within a control 
section that defines an entry point, and 
can be referred to for execution by any 
control section. 


exclusive reference. A reference 
between exclusive segments; that is» a 
reference from a segment in storage to 
an external symbol in a segment that 
will cause overlay of the calling 
segment. 


exclusive segments. Segments in the 
same region of an overlay program, 
neither of which is in the path of the 
other; they cannot be in virtual storage 
simultaneously. 


external name. <A name that can be 
referred to by any control section or 
separately assembled or compiled module; 
that is, a control section name or an 
entry name. 


external page storage. The portion of 
auxiliary storage that is used to 
contain pages. 


external reference. (1) A reference to 
a symbol that ts defined as an external 
name in another module. (2) An external 
symbol that is defined in another 
module; that which is defined in the 
Assembler language by an EXTRN statement 
or by a V-type address constant, and is 
resolved during linkage editing. See 
also weak external reference. 
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external symbol. <A control section 
name, entry point name, or external 
reference that is defined or referred to 
in a particular module. A symbol 
contained in the external symbol 
dictionary. 


external symbol dictionary (ESD). 
Control information, associated with an 
object or load module that identifies 
the external symbols in the module. 


inclusive reference. A reference 
between inclusive segments; that is, a 
reference from a segment in storage to 
an external symbol in a segment that 
will not cause overlay of the calling 
segment. 


inclusive segments. Segments in the 
same region of an overlay program that 
are in the same path; they can be in 
virtual storage simultaneously. 


invalid exclusive reference. An 
exclusive reference in which a common 
segment does not contain a reference to 
the symbol used in the exclusive 
reference. 


library. In this publication, a 
partitioned data set that always 
contains named members. 


load module. The output of the linkage 
editor; a program ina format suitable 
for loading into virtual storage for 
execution. 


load module buffer. An entity of 
virtual storage used by the linkage 
editor to read input load module text 
records and possibly to retain the text 
information in storage for subsequent 
writing of the output load module text 
records. 


xmodule. <A program unit that is 
discrete and identifiable with respect 
to compiling, combining with other 
units, and loading, for example, the 
input to, or output from, an assembler, 
compiler, linkage editor, or executive 
routine. 


multiple load module processing. A 
method of processing whereby two or more 
load modules can be produced ina single 
linkage editor job step. 


xobject module. <A module that is the 
output of an assembler or compiler and 
1s input to a linkage editor. 


overlay program. A program in which 
certain control sections can use the 
same storage locations at different 
times during execution. 


xoverlay supervisor. A routine that 
controls the proper sequencing and 
positioning of segments of computer 
Programs in limited storage during their 
execution. 
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overlay tree. A graphic representation 
showing the relationships of segments of 
an overlay program and how the segments 
are arranged to use the same main 
storage area at different times. 


page. C1) A fixed-length block of 
instructions, data, or both, that can be 
transferred between real storage and 
external page storage. (2) To transfer 
instructions, data, or both between real 
storage and external page storage. 


page fault. A program interruption that 
occurs when a page that 15 marked "not 
in real storage” is referred to by an 
active page. 


paging. The process of transferring 
pages between real storage and external 
page storage. 


path. All of the segments in an overlay 
tree between a given segment and the 
root segment, inclusive. 

private code. An unnamed control 
section. 


program. A logically self-contained 
sequence of operations or instructions 
that, when followed in some 
predetermined sequence, will produce a 
specified result; a sequence of 
instructions to be performed by a 
computer; one or more modules, in source 
language or relocatable object code, or 
one module in executable code, that 15 a 
logically self-contained process. 


program fetch. <A program that prepares 
load modules for execution by loading 
them at specific storage locations; it 
also readjusts each address constant. 


pseudo-register. In PL/I, a location in 
virtual storage that is used as a 
pointer to dynamically acquired virtual 
storage. It enables the PL/I compiler 
to generate reenterable code. External 
dummy sections give the programmer using 
Assembler F or Assembler H the same 
facility. 


real storage. The storage from which 
the central processing unit can directly 
obtain instructions and data, and to 
which it can directly return results. 


reenterable load module. A module that 
can be used concurrently by more than 
one task. 


refreshable load module. A load module 
that cannot be modified by itself or by 
any other module during execution; can 
be replaced by a new copy during 
execution by a recovery management 
routine without changing either the 
sequence or results of processing. 


J 


region. In an overlay structure, a 
contiguous area of virtual storage 
within which segments can be loaded 
independently of paths in other regions. 
Only one path within a region can be in 
virtual storage at any one time. 


relocation. The modification of address 
constants required to compensate for a 
change of origin of a module, program, 


- or control section. 


RSECT. 
nucleus. 


A read-only CSECT in the 


root segment. That segment of an 
overlay program that remains in virtual 
storage at all times during the 
execution of the overlay program; the 
first segment in an overlay program. 


residence mode (RMODE). Defines whether 
the program must be resident in storage 
addressable by 24-bit addressing or 31- 
bit addressing. 


scatter format. <A load module attribute 
that permits the control program to 
dynamically load control sections into 
noncontiguous areas of virtual storage. 


segment. The smallest functional unit 
Lone or more control sections) that can 
be loaded as one logical entity during 
execution of an overlay program. 


serially reusable load module. A module 
that cannot be used by a second task 
until the first task has finished using 
it. 


source module. The source statements 
that constitute the input to a language 
translator for a particular translation. 


storage block. <A 2K-byte block of real 
storage to which a storage key can be 
assigned, processor-model dependent. 


upward reference. A reference made from 
a segment to another segment higher in 
the same path; that is, closer to the 
root segment. 


valid exclusive reference. An exclusive 
reference in which a common segment 
contains a reference to the symbol used 
in the exclusive reference. 


virtual address. An address that refers 
to virtual storage and must, therefore, 
be translated into a real storage 
address when it is used. 


virtual storage. Addressable space that 
appears to the user as real storage, 
from which instructions and data are 
mapped into real storage locations. The 
size of virtual storage is limited by 
the addressing scheme of the computing 
system and the amount of auxiliary 
storage available, rather than by the 
actual number of real storage locations. 


Weak external reference. An external 
reference that does not have to be 
resolved during linkage editing. If it 
is not resolved, it appears as though 
its value was resolved to zero. 
Abbreviated WXTRN. 
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SPRIVATE 43 
**¥GO 166 
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A-type address constant 
replacing control sections 49, 134 
SEGNT macro 84 
AC option 15, 89 
adcons 
See address constant 
additional call libraries 27 
additional input sources 
automatic call library 24-28 
general description of 12, 19 
included data sets 29-32 
libraries 24-32 
processing of 24-32 
specification of 
automatic call library 26 
INCLUDE statement 30-32 
LIBRARY statement 26, 123 
address 

assignment 8 

of main entry point 
module map 43 
specifications 36 

sequence in object module text 6 

address constant 4, 6 
See also A-type, V-type address 

constant 
resolution of 4-6 

addressing mode 

assignment 

linkage editor 15 
combinations 

residence mode 90 
control section name 5 
default 16 
entry point 37 
linkage editor Il 
options 77 
override 16 
parameter 

linkage editor 8&9 
private code 5 

alias name 
example 35 
linkage editor 85 
loader 170 
specifying 35 

ALIAS statement 35, 114 

alignment, page 56 

alternate output data set 
See SYSTERM data set 

AMODE 
See addressing mode 

assigning block size, linkage 

editor 104 

asynchronous overlay supervisor 80 

attributes, module 
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See module attributes 
authorization codes 

See AC option 
Authorized Program Facility (APF) 15 
automatic call library for loader 

DD statement for 168 

description of 160 

options 164 
automatic call library mechanism 43 

See also call library, linkage editor 

module map 43 
automatic deletion of modules 160 
automatic replacement 

control sections 49-51 

examples 49-51 

modules 35 

note on overlay programs 49 
automatic search 

of link pack area queue 166 

of SYSLIB 165 


blank common area 
collection of 37, 77 
definition 5 
module map 43 
BLKSIZE operand (DCB macro) 101-107 
block size 101-107 
blocking factors, SIZE option 96, 159 
branch instructions, in overlay 
programs 80-82 
buffer, load module 
See load module buffer 
BUFNO operand (DCB macro) 
loader DD statements)9 168 
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call library, linkage editor 
additional libraries 27 
concatenating 26 
ddname 25 
example 25 
NCAL option 28 
negating 28, 92 
never-call 28 
restricted no-call 27 
specification of 25-26 
call library, loader 
DD statement for 168-170 
description 160 
options for use 164 
CALL loader option 165 
CALL macro 
definition 80 
invoking the loader 173 
with only loadable attribute 87 
capacities, linkage editor 155 
cataloged procedure 
adding DD statements 111 
definition 107 


linkage editor 107 
LKED 107-109 
LKEDG 109-110 
overriding 110-111 
CESD 
See composite external symbol 
dictionary 
CHANGE statement 
example 47 
summary 115-116 
using INCLUDE statement 55 
using REPLACE statement 55 
changing external symbols 47 
class test table 67 
collection of common areas 37, 77-79 
common area 
blank 5 
collection of 37, 77, 79 
definition 5 
lengthening 15, 118 
module map 42 
named 5 
ordering named 55-56 
reserving storage for 37 
common segment 
definition 65 
exclusive references) 65 
promotion of common areas 77 
comparison of linkage editor and 
loader 1, 160 
compatibility, linkage editor and 
loader 163 
composite external symbol dictionary 
definition 
number of entries permitted 156 
concatenation 
call libraries 26 
data sets 
linkage editor 3l 
loader 168 
restrictions 107 
COND parameter 
determining load module 
execution 100 
in LKEDG 109 
specified in EXEC statement 100 
specified in JOB statement 100 
condition parameter 
See COND parameter 
constant 
See address constant 
control dictionaries 4 
control section 
aligning on page boundary 56 
definition 3 
deleting 53 
external symbol dictionary 4 
lengthening 15, 
module map 42 
name 
changing 47 
external symbol dictionary 4 
ordering of 55-56 
positioning 73 
replacing 48 
control statements 
as input 22 
concatenating object module data 
set 22 
continuation of 112 
format conventions) 112 
general format 112 
listing 41 
listing option 98 


placement information 112 
summary list 112 

cross reference table 
option 98 
Producing 43 
sample 44 

CSECT identification records 
function 15 
object and load modules 4 
storage required 15/7 
using IDENTIFY statement 119 
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data definition statements 
See DD statements 
data for loaded program 170 
data set 
concatenation of 26, 31, 168-170 
linkage editor 
input 19 
output 33 
loader 168 
DCB information 
linkage editor 101 
loader 168 
DCBS option, block size 97 
DD statement 
general description 101 
linkage editor data sets 
ddnames)9 101-103 
SYSLIB 27, 103 
SYSLIN 102 
SYSLMOD 104 
SYSPRINT 104 
SYSTERM 105 
SYSUT1 103 
loader data sets 
ddnames 168, 171 
SYSLIB 169 
SYSLIN 168 
SYSLOUT 169 
SYSTERM 170 
ddname list 153 
ddnames, linkage editor 
invoking 101-107 
loader 
automatic call library 168 
diagnostic data set 170 
input data set 168 
specifying alternate names’) 153, 
171 
default module attributes 90 
deleting a control section 53 
deleting an entry name 53 
deleting modules'79 160 
diagnostic messages 
linkage editor 
directory 39 
format 39-41 


loader 
defined by SYSLOUT DD and SYSTERM 
DD 174 


format 174 
diagnostic output 
linkage editor 
messages 9 
optional 41-44 
options, summary 14-15 
loader 
data set 170 
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format 174 
options 164 
dictionaries 
composite external symbol 7, 156 
external symbol 5 
relocation 4, 6, 155 
directory entry 
authorization code 37 
changing 48 
disposition messages 39-40 
downward call 
See downward reference 
downward reference 
definition 58 
maximum number 157 
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editing 
conventions 45-46 
module 45-46 
end of module indication 7 
END statement 
object module 4 
specifying entry point 36 
ENTAB Centry table) 68 
entry address, module map 43 
entry name 
definition 5 
ESD 
changing 47 
deleting 53 
module map 42 
entry point 
example 36 
loaded program 165, 173 
specification of 
END statement 36 
ENTRY statement 36, 117 
ENTRY statement 
main entry point 36 
summary 117 
entry table 68 
EOM Cend of module indication) 7 
EP loader option 165 
error conditions 
See severity code 
error messages 
See diagnostic messages 
ESD Cexternal symbol dictionary) 5 
exclusive call option 91 
exclusive reference 
definition 64 
entry table 68 
restrictions 65 
segment table 68 
XCAL option 91 
exclusive segments 
note on overlay programs 49 
EXEC statement 
linkage editor 
introduction 85 
job step options 85 
program name _ 85 
REGION parameter 100 
return code 100 
loader 
description 164, 167 
examples 167 
executable module 90 
EXPAND statement 15, 118 
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external dummy section 5, 13, 38 
See also pseudo register 
definition 5 
processing of 13> 38 

external name 
See also control section name, entry 

name 
definition 3 

external reference 
changing 47 
definition 3, 5 
external symbol dictionary 5 
resolving 9, 24 
weak 

automatic library-call 24 
cross reference table 44 
external symbol 
changing 47 
definition 3 
external symbol dictionary 5 
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functions 
linkage editor 9-10 
loader 160 
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HEWL 85, 107 
HEWLOAD 172, 174 
HEWLOADR 172 
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IDENTIFY statement summary 119 
IDR 
See CSECT identification records 
IEBUPDTE program 
input statements 149 
INCLUDE statement 
requesting additional data sets as 
Input 29 
specifying ddname of DD statement 29 
summary 121 
included data sets 
concatenated data sets 30 
library members 30 
linkage editor 29 
sequential data sets) 30 
inclusive reference 
when to use 65 
inclusive segments 
definition 64 
incompatible job step options 99 
incompatible module attributes 9 
input data sets 
linkage editor 19 
loader 168 
input processing 19 
input sources 
linkage editor 7 
loader 164, 168 
INSERT statement 
summary 122 


using 75 
intermediate data set 

devices supported 158 

linkage editor /7 

leader 163 

SIZE option 92, 155 

storage required 155 

SYSUT1 DD statement 103 
intermediate text records, number 
produced 157 
internal data area 163 
- invalid attributes or options 39 
invalid exclusive reference 

illustration 66 
invocation of 

linkage editor 153 

loader 170 
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job control language summary 85 
job control statements 
linkage editor 85 
loader processing 
basic format 164 
compile-load job 176 
load job 178 
multiple compilations 176 
job step 
options 
EXEC statement 85 


let execute option 31 
LET option 
linkage editor 91, 145 
loader 163, 165 
overlay programs 77 
library call 
See automatic call library for loader 
library members 
including 30 
input to linkage editor 20 
input to loader 168 
LIBRARY statement 
additional call libraries 27 
NCAL option 92 
never-call function 28 
restricted no-call function 27 
summary 123 


using 26 
LINK command 18 
LINK macro 
invoking 
linkage editor 153 
loader 172 
link pack area resolution 
loader 166 


linkage editor 
assigning block size 104 
capacities 155 
cataloged procedures'7 107 
compared to loader 1, 160 
control statement summary 112 
DD statements 102-107 


functions 9-10 
input 
additional data sets 19 
control statements 23 
object modules 23 
primary data sets 19 
invoking 153 
output 33 
processing 7 
relationship to operating system 18 
storage requirements) 155 
when to use 1 
LINKEDIT 85 
linking modules’79 10 
LIST option 41, 98 
LKED procedure 107-109 
LKEDG procedure 109-110 
LOAD macro 
invoking the loader 173 
only loadable modules 87 
load module 
attribute assignment 14 
attributes 86 
buffer 92 
definition 2 
entry point 36 
input 
linkage editor 19 
loader 164 
linkage editor output 33 
multiple processing of 38 
structure 4 
load module buffer 
allocating storage 92 
load module creation 7 
load module format 
loader 
example 
load point 63, 71 
load step 1, 164 
loaded program 
data 170 
module map 175 
options 164, 167 
return codes’ 178 


loader 
abnormal termination message 
CVS2) 175 


alias name 170 
compared to linkage editor 1, 160 
compatibility with linkage 
editor 163 
data sets 168 
input 160, 164 
invoking 170 
options 164, 167 
output 174 
program name 170 
restrictions 163 
return codes’ 178 
when to use 1 
LOADGO command 163 
loading 
with tdentification 174 
without identification 173 
logical record length 
linkage editor data sets 
blocking factors) 102 
diagnostic output 104 
input 102 
SIZE option 92 


LRECL operand (DCB macro) 101-102 
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macros, linkage editor 
format 153 
MAP option 
linkage editor 
loader 163, 166 
maximum record size for device 
types 93-94 
member name 
definition 34 
example 34 
specifying 34 
member, partitioned data set 
including 30 
input to the linkage editor 20 
input to the loader 168 
messages 
disposition 
examples 41 
format 40 
text 41 
unnumbered 40 
MODE statement 
example 126 
specifying addressing mode 125 
specifying residence mode 125 
summary 125-126 
values 125 
modular programming 2 
module attributes 
default attributes 90 
describing output module 86 
incompatible attributes 91, 99 
not editable 87 
not-executable 99 
only loadable 87 
overlay 87 
refreshable 88 
reusability 
reenterable 87 
serially reusable 87 
scatter format 86 
test 88 
module disposition messages 39 
module editing 
general description 45 
summary 11 
module linking 
module map 
linkage editor 
description 42-43 
example 43 
MAP option 98 
loader 
description 175 
example 175 
specifying 166 
module, definition 2 
multiple load module processing 
producing 38 
multiple region overlay program 
general description 68 
specifying 72 
using 68 


42-43, 98 


39-40 


10-12 
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NAME loader option 166 
NAME statement 
multiple load module processing 38 
replace function 35 
summary 127 
SYSLMOD DD 34 
named common area 
aligning on page boundary 56 
collection of 37, 
definition 5 
module map 42 
NCAL option 
linkage editor 28, 91 
loader 163, 165 
NE attribute 87 
negation of automatic library call 
linkage editor 28 
loader 
diagnostic output 166 
module map 166 
search of link pack area _ 166 
not editable attribute 87 
not executable attribute 92 
reenterable attribute 88 
refreshable attribute 88 
serially reusable 88% 
never-call function 
cross reference table 44 
specifying external references 28 
no automatic library call option 91 
no-call 28 
NOCALL loader option 165 
node point 
See load point 
NOLET loader option 165 
NOMAP loader option 166 
NOPRINT loader option 166 
NORES loader option 166 
not editable attribute 
linkage editor 87 
loader 163 
not-executable attribute 91 
NOTERM loader option 167 


Lo | 


object module 
definition 2 
input to linkage editor 23 
input to loader 168 
structure 4 
virtual storage 163 
OL attribute 87 
only loadable attribute 8/7 
optional output 41 
options, incompatible 99 
options, linkage editor 
addressing mode 77 
module attributes 8&6 
output 98 
residence mode 77 
space allocation 92 
special processing 91-92 
ORDER statement 55-56, 128 
origin 
control section in module map 42 
region 72 


segments 63 
output module library 33 
output of linkage editor 
diagnostic messages 39 
load module 33 
optional output 41-44 
output module library 33 
output options 98 
output of the loader 
messages 174 
module map 175 
specifying 164-167 
output text record length 155 
overlap of loading and processing, 
overlay segments) 82 
overlay attribute 
specifying 8/7 
overlay program 
communication 80 
design 58 
module map 42 
multiple region 68 
Process 67-68 
region origin 72 
respecifying control statements 71 
sample program 143-149 
segment origin 63, 71 
single region 59 
special considerations 77 
specifying 70 
storage requirements) 79-80 
OVERLAY statement 
specifying 70-76 
summary 130 
overlay supervisor, definition 67 
overlay tree 
positioning segments 61 
overriding cataloged procedures 
DD statements 111 
EXEC statement 110 
OVLY attribute 87 
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page boundary 
aligning control sections or named 
common areas 56 
PAGE statement 
aligning control sections 56 
summary 132 
parameter 
addressing mode 89 
combination 89 
residence mode 89 
partitioned data set 


Input 
linkage editor 20 
loader 168 
output, linkage editor 33 
path 


in overlay program 58 
placement of control statements 112 
positioning control sections 73 
preloaded text 163, 175 
primary input data set 

control statements 22 

job control language 

specifications 19 

object modules 19, 23 
PRINT loader option 166 
private call libraries 26 


private code 
definition 5 
module map 43 
procedure LKED 107-109 
procedure LKEDG 109-110 
processing history, tracing 
CSECT Identification record 15 
processing options, special 91 
program fetch 
functions 8 
prompter 
linkage editor, function of 18 
loader, function of 163 
pseudo register 
definition 5 
module map 43 
processing of 13, 38 
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read-only attribute, assignment 18 
RECFM 
See record format 
record format (CRECFM) 
linkage editor data sets 
diagnostic output 107 
input 101-102 
load modules 102-107 
loader data sets) 168 
record size 
maximum 
device type 93 
reenterable attribute 8&7 
reenterable load module 
module attribute 88 
REFR attribute 88% 
refreshable attribute 88 
refreshable load module 
module attribute 91 
REGION parameter 
specifying storage 100 
region, overlay programs 
specifying 72 
using 68 
region, virtual storage 
linkage editor 
cataloged procedures) 107 
SIZE option 97 
loader 173 
relocating a load module 2 
relocation dictionary 
number of entries 155 
using 6 
RENT attribute 88% 
replace function 35, 48-54 
REPLACE statement 
deleting CSECT 54 
example 52 
sample program 139-143 
summary 134-135 
using 51 
replacing control sections, assembler 
language note 48 
replacing external symbols 
See CHANGE statement, changing 
external symbols 
replacing load modules with the same 
name 35 
repositioning control statements 
automatic call library 76 
INSERT control statement 73, 122 
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reprocessing load modules 
entry point assignment 36 
not editable attribute 87 
RES loader option 166 
reserving storage 37 
residence mode 
assignment 
linkage editor 16 
output load module 33 
combinations 
addressing mode 90 
control section name 5 
default 17 
entry potnt 37 
options 77 
override 17 
parameter 
linkage editor 89 
private code 5 
resolving external references 9, 24 
restricted no-call function 27 
restrictions, virtual storage size 
requirements)9 89 
return codes 
linkage editor 100 
loader 178 
severity code 40 
REUS attribute 87 
reusability attributes 
general description 8&7 
reenterable 87 
serially reusable 87 
RLD 
See relocation dictionary 
RMODE 
See residence mode 
root segments 
definition 58 
OVERLAY 71 
segment table 68 
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sample programs 138 
scatter loading 8&6 
SCTR attribute 86 
SEGLD macro 80 
segment 61, 63, 64, 67 
See also exclusive, inclusive, root 
segments 
communication 64-67 
dependency 61 
origin 63 
segment load macro 827-83 
segment table 68 
segment wait macro 
SEGLD 84 
using 83 
SEGTAB (segment table) 68 
SEGNT macro 
SEGLD 84 
using 83 
sequential data set 
INCLUDE statement 30 
input to linkage editor 19, 30 
input to loader 168 
serially reusable 
attribute 88 
SETCODE statement 15, 136 
SETSSI statement 137 
severity code 
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linkage editor messages 40 
return codes)7 100 
severity 0,2 errors) 40 
SIZE option 
linkage editor 92, 159 
loader 167, 180 
space allocation 
DCBS option 97 
maximum values 92, 95 
minimum values 92, 95 
SIZE option 92 
specifying storage 92 
special processing options 
affecting automatic library call 
mechanism 91 
affecting output module 91 
summary 14 
static external areas 37 
SYSLIB DD statement 
automatic call library 24 
linkage editor 103 
loader 169 
SYSLIN DD statement 102, 168 
See also automatic call library for 
loader 
linkage editor 102, 168 
SYSLMOD DD statement 38, 39, 104 
See also output module library 
function 104 
NAME statement 38-39 
referenced by INCLUDE statement 104 
SYSLOUT DD statement 166, 169 
SYSPRINT DD statement 104 
system call library 
example 25 


list 25 
a ra status index information, storage ) 
oO 14 
SYSTERM data set 

linkage editor 41, 98, 105 

loader 168, 170, 174 
SYSTERM DD statement 

linkage editor 41, 98, 105 

loader 168, 170, 174 
SYSUT1 DD statement 103 


TEMPNAME 34 
temporary data set 21, 34 
TERM option 
linkage editor 41, 98, 106 
loader 167 
TEST attribute 88 
text 
message 41 
note 6 
processing out-of-order 4 
time sharing option 
See TSO 
tracing processing history 15 
TRANSFORM table 67 
tree structure 
positioning of segments) 61 
purpose of 60 
TSO (time sharing option) 
linkage editor 
invoking 18 3 
SYSTERM data set 106 
TERM option 41 
loader 


invoking 163 
SYSTERM data set 167, 170 
TERM option 167 
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unnumbered messages 39-40 
unresolved references 
automatic library-call, resolving 
with 24 
cross reference table 44 
upward reference, definition 58 
user-specified 
input 7 
storage 14 
user-written library 25 
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V-type address constant 
branch instruction, overlay 82 
CALL 82 
SEGLD 83 
SEGNT 84 
valid exclusive reference 65 


virtual storage requirements 
linkage editor 155 
loader 180 
overlay programs) 79-80 
restrictions 89 
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wait for loading of segment 83 

warning messages 40-41 

weak external reference 
automatic library-call 24 
cross reference table 44 
definition 5 
level F linkage editor 12 
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XCAL option 77, 931 
XCTL macro 
input to loader 163 
invoking the loader 171 
XREF option 98 
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